Skip to content

Latest commit

 

History

History
29 lines (18 loc) · 3.35 KB

introspection.md

File metadata and controls

29 lines (18 loc) · 3.35 KB
Raw

Introspection

When working with an existing database, the first step towards using Prisma 2 is to obtain a Prisma schema that matches your database schema (or a subset of your database schema). You can create this schema file manually and write out all the required models by hand, or use Prisma's introspection feature to automatically generate your Prisma schema.

Prisma lets you introspect your database to derive a data model definition from the current database schema. Introspection is available via either of two CLI commands:

  • prisma2 init: Interactive wizard that helps you connect to a database and introspect it. Typically used when starting to use Prisma with an existing database.
  • prisma2 introspect: Assumes Prisma is already connected to your database and (re)introspects it for you. Typically used in "Prisma Client"-only projects where migrations are performed not via Prisma's migrate command, so the data model needs to be updated manually after each database schema change.

Note that prisma2 introspect requires the connection string for the database you want to introspect. Therefore, you either need to run the command inside of a directory that contains a Prisma schema with a valid datasource definition (which contains the connection string) or pass the --url argument, e.g.:

prisma2 introspect --url postgresql://janedoe:mypassword42@localhost:5432/mydb

Introspecting only a subset of your database schema

This is not yet supported by Prisma. However, you can achieve this by creating a new database user that only has access to the tables which you'd like to see represented in your Prisma schema, and then perform the introspection using that user. The introspection will then only include the tables the new user has access to.

Conventions

As database schemas are likely to look very different per project, Prisma employs a number of conventions for translating a database schema into a data model definition:

  • Field, model and enum names (identifiers) must start with a letter and generally must only contain underscores, letters and digits.
  • If invalid characters appear before a letter in an identifier, they get dropped. If they appear after the initial letter, they are replaced by an underscorce. Additionally, the transformed name is mapped to the database using @map or @@map to retain the original name.
  • If sanitization results in duplicate identifiers, no immediate error handling is in place. You get the error later and can manually fix it.
  • Relation names for a relation between models A and B are generated as AToB (the model that comes first in alphabetical order also appears first in the generated relation name). If relation names turn out to be ambiguous because there is more than one relation between models A and B, the field name of the column that holds the foreign key is appended to the model name after an underscore to disambiguate, e.g.: A_FieldWithFKToB.
  • The name of the back-relation field is based on the opposing model. It gets camel cases by defauld and pluralized (unless the column with the foreign key also has a unique constraint). If back-relation fields are ambiguous, the relation name is appended to disambiguate.