src Documentation

Official TypeScript developer resources and documentation for MichalLytek/src. Verified technical context for AI.

0 stars TypeScript TypeScript 1 file · ~13,351 tokens
RAW Doc

1. Project Overview & Quickstart (MichalLytek/src)

src

Open-source repository MichalLytek/src

Repository Details

Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.

2. Official Technical Reference & Guides (MichalLytek/docs)

File: README.md

Prisma Documentation

This repository contains the source code and the content for the Prisma documentation.

Run locally

Clone this repository and get started by running the following commands:

text
npm install
npm run dev

To prettify or format the code, run:

text
npm run prettify

Visit http://localhost:8000/ to view the app.

Configure

Write MDX files in content folder.

Open config.js for available config options for gatsby, header, footer and siteMetadata.

  • gatsby config for global configuration like

    • pathPrefix - Gatsby Path Prefix

  • header config for site header configuration like

    • title - The title that appears on the top left
    • links - The links for header
    • logoLink - The link to redirect on logo click

  • footer config for site footer configuration like

    • title - The title that appears on the top left
    • logoLink - The link to redirect on logo click
    • products, community, company, resources - The links for various footer
    • newsletter - Newsletter config
    • findus - Social links

  • siteMetadata config for website related configuration

    • title - Title of the website in main page
    • description - Description of the website
    • keywords - Keywords of the website for SEO

Inserting, moving and deleting files

All files/folders in the context are prefixed with a position which indicates the order in which they appear in the sidenav on the docs website. This makes it cumbersome to insert, move and delete files because the positions of a number of other files (if not all) in the same folder might need to be adjusted. Thanks to Luca Steeb, you can perform these operations with a dedicated CLI called mdtool.

Install

bash
wget https://gist.githubusercontent.com/steebchen/bd085ebde1fcf4242e3fdd0df4d202a6/raw/c04e3d262eb6a302a9fab98f6428fec9329681e2/mdtool -qO /usr/local/bin/mdtool
chmod +x /usr/local/bin/mdtool

Usage

Overview

text
mdtool insert 3
mdtool swap A B
mdtool move A B
mdtool remove 4

`mdtool insert`

Make place for a new file at given index and increment all numbers by one after that index:

text
$ mdtool insert INDEX

# e.g.:
$ mdtool insert 2

# Result: for files 01-a, 02-b, 03-c, and 04-d; 03-c is renamed to 04-c and 04-d is renamed to 05-d so you can create a new file at index 2

`mdtool swap`

Swap two files; specify both filenames (prefix numbers get automatically adjusted):

text
$ mdtool swap FILENAME1 FILENAME2

# e.g.:
$ mdtool swap 03-file1.mdx 07-file2.mdx

# Result: Files are now named: 03-file2.mdx 07-file1.mdx

`mdtool move`

Move a given file to another given index

text
$ mdtool move FILENAME INDEX

# e.g.:
$ mdtool move 05-file.mdx 2

# Result: 05-file.mdx is move to 02-file.mdx, plus previous files 02-*, 03-*, 04-* are incremented

`mdtool swap`

Shift all other items by -1 at a given index:

text
$ mdtool remove INDEX

# e.g.:
$ mdtool remove 2

# Result: 01-a, 02-b, 03-c, 04-d becomes 01-a, 02-b, 02-c, 03-d; 02-b is supposed to be manually deleted

Thanks Luca

File: content/600-about/02-style-guide/01-mdx-examples.mdx

title: 'MDX components' metaTitle: 'MDX components in the Prisma docs' metaDescription: 'MDX components components available on the Prisma documentation site.' navTitle: 'MDX components'

This page describes how to use MDX components (e.g. code blocks) in the Prisma docs.

TopBlock

Required at the top of the page to avoid styling issues:

md
<TopBlock>

This page describes how to use [MDX](https://mdxjs.com/) components (e.g. code blocks) in the Prisma docs.

</TopBlock>

Code blocks

Example:

js
async function main() {
  const allUsers = await prisma.user.findMany()
  console.log(allUsers)
}

Code:

no-lines
```js
async function main() {
const allUsers = await prisma.user.findMany()
console.log(allUsers)
}
```

Prisma schema

Example:

prisma
datasource db {
  provider = "sqlite"
  url      = env("DATABASE_URL")
}
generator client {
  provider = "prisma-client-js"
}
model Post {
  id        Int     @id @default(autoincrement())
  title     String
  content   String?
  published Boolean @default(false)
  author    User?   @relation(fields: [authorId], references: [id])
  authorId  Int?
}
model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
  posts Post[]
}

Code:

no-lines
```prisma
datasource db {
  provider = "sqlite"
  url      = env("DATABASE_URL")
}
generator client {
  provider = "prisma-client-js"
}
model Post {
  id        Int     @id @default(autoincrement())
  title     String
  content   String?
  published Boolean @default(false)
  author    User?   @relation(fields: [authorId], references: [id])
  authorId  Int?
}
model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
  posts Post[]
}
```

Code block with file icon

Example:

prisma file=schema.prisma
datasource db {
  provider = "sqlite"
  url      = env("DATABASE_URL")
}
generator client {
  provider = "prisma-client-js"
}
model Post {
  id        Int     @id @default(autoincrement())
  title     String
  content   String?
  published Boolean @default(false)
  author    User?   @relation(fields: [authorId], references: [id])
  authorId  Int?
}
model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
  posts Post[]
}

Code:

text
```prisma file=schema.prisma
datasource db {
  provider = "sqlite"
  url      = env("DATABASE_URL")
}
generator client {
  provider = "prisma-client-js"
}
model Post {
  id        Int     @id @default(autoincrement())
  title     String
  content   String?
  published Boolean @default(false)
  author    User?   @relation(fields: [authorId], references: [id])
  authorId  Int?
}
model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
  posts Post[]
}
```

Code block with copy

Example:

js copy
async function main() {
  const allUsers = await prisma.user.findMany()
  console.log(allUsers)
}

Code:

no-lines
```js copy
async function main() {
  const allUsers = await prisma.user.findMany()
  console.log(allUsers)
}
```

Code block without line numbers

Example:

js no-lines
async function main() {
  const allUsers = await prisma.user.findMany()
  console.log(allUsers)
}

Code:

text
```js no-lines
async function main() {
  const allUsers = await prisma.user.findMany()
  console.log(allUsers)
}
```

Code block with highlighted code

Example:

js file=test.ts highlight=2;add|4;delete|6,7;edit|9-12;normal
async function main() {
  added code

  deleted code

  edited
  code

  highlights
  over multiple
  lines can be done by using
  a hyphen
}

Code:

no-lines
```js file=test.ts highlight=2;add|4;delete|6,7;edit|9-12;normal
async function main() {
  added code

  deleted code

  edited
  code

  highlights
  over multiple
  lines can be done by using
  a hyphen
}
```

File icons

There are 4 icons available:

no-lines
<FileWithIcon text="file.pdf" icon="file"/>
<FileWithIcon text="dev.db" icon="database"/>
<FileWithIcon text="Windows" icon="display"/>
<FileWithIcon text="schema.ts" icon="code"/>
<FileWithIcon text="prisma.schema" icon="prisma"/>

Tabbed blocks

Example:

<TabbedContent tabs={[, ]}>

id email name
1 "[email protected]" "Sarah"
2 "[email protected]" "Maria"
copy bash-symbol
npm run dev

Code:

no-lines
<TabbedContent tabs={[<FileWithIcon text="schema.ts" icon="file"/>, <FileWithIcon text="dev.db" icon="database"/>]}>

<tab>

| **id** | **email**           | **name**  |
| :----- | :------------------ | :-------- |
| `1`    | `"[email protected]"` | `"Sarah"` |
| `2`    | `"[email protected]"` | `"Maria"` |

</tab>

<tab>

```copy bash-symbol
npm run dev
```

</tab>

</TabbedContent>

Subsections

Lists all child pages of the current page to the specified depth:

text
<Subsections depth="3" />

Expand/Collapse section

Example:

Expand if you want to view more

Here's more!

no-lines
Expand if you want to view more

Here's more!

Example:

Button text

Code:

text
Button text

Code with output

Example:

text
yarn prisma init
text
$ yarn prisma init
yarn run v1.22.0
warning package.json: No license field
$ /Users/nikolasburk/Desktop/tsdf/node_modules/.bin/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 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.
2. Set the provider of the datasource block in schema.prisma to match your database: postgresql, mysql or sqlite.
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

Code:

text
<CodeWithResult expanded={true}>

<cmd>

```
yarn prisma init
```

</cmd>

<cmdResult>

```
$ yarn prisma init
yarn run v1.22.0
warning package.json: No license field
$ /Users/nikolasburk/Desktop/tsdf/node_modules/.bin/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 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.
2. Set the provider of the datasource block in schema.prisma to match your database: postgresql, mysql or sqlite.
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
```

</cmdResult>

</CodeWithResult>

Quiz component

Example:

<Quiz
question="Can Prisma be used with Node.js?"
answerOptions={
[
{
answer: 'It only works with potatoes',
isCorrect: true
},
{
answer: 'It can be used with any Java backend!',
isCorrect: false
},
{
answer: 'It can be used with any Node.js or TypeScript backend!',
isCorrect: false
},
{
answer: 'It can be used with a Python backend!',
isCorrect: false
}
]
}
/>

Code:

ts
<Quiz
question="Can Prisma be used with Node.js?"
answerOptions={
  [
    {
      answer: 'It only works with potatoes',
      isCorrect: true
    },
    {
      answer: 'It can be used with any Java backend!',
      isCorrect: false
    },
    {
      answer: 'It can be used with any Node.js or TypeScript backend!',
      isCorrect: false
    },
    {
      answer: 'It can be used with a Python backend!',
      isCorrect: false
    }
  ]
  }
/>

Tip component

Example:

To find out if Prisma is the right fit for your project, head on over to What is Prisma and read all about what makes Prisma, Prisma!

Code:

text
<Tip>

  To find out if Prisma is the right fit for your project, head on over to [What is Prisma](../../concepts/overview/what-is-prisma) and read all about what makes Prisma, Prisma!

</Tip>

File: content/600-about/02-style-guide/02-template.mdx

title: 'Writing template' metaTitle: 'Writing template (About)' metaDescription: 'A template for writing Prisma Docs.' tocDepth: 2 hidePage: false toc: true

A short introduction that encourages visitors to read on. The TopBlock component is required for styling purposes.

A section

Break your page up into sections. Use the tocDepth frontmatter variable to determine how many levels the table of contents should have - 1 or 2.

A subsection

If possible, avoid too many deeply nested subsections.

File: content/600-about/02-style-guide/03-frontmatter.mdx

title: Frontmatter metaDescription: "Supported frontmatter variables."

title

The <h1> title of the page.

metaTitle

The <title> of the page - falls back to title (h1)

Allows you to specify a different, usually shorter title for the left-hand navigation.

metaDescription

The <meta name="description" content="" /> of the page.

Turns the page into a non-linked heading in the left-hand navigation. For example: https://www.prisma.io/docs/concepts/overview

Note: The page still exists, but you can only navigate to it via the breadcrumb.

preview

Adds a preview label to a page in the left-hand navigation.

toc

Enable or disable table of contents navigation on the page (defaults to false). For example:

text
toc: true

tocDepth

Controls the depth of headings to show in the ToC:

text
tocDepth: 2

Note: Currently limited to 2 levels - h2 and h3

hidePage

Hides page from all navigation (still visible through search). For example:

text
hidePage: true

File: content/600-about/02-style-guide/index.mdx

title: 'Prisma style guide' metaTitle: 'Prisma documentation style guide' metaDescription: 'The Prisma style guide contains a number of rules and conventions for the content in the Prisma documentation.' tocDepth: 2

Welcome! This guide contains information for writing and maintaining technical documentation for the Prisma tools. One major goal of this style guide is to ensure consistency in the Prisma documentation with respect to things like word choice, writing style, formatting and more.

This style guide is heavily inspired by the Gatsby Style Guide. Many sections have been bluntly copied, some others have been slightly edited and some are new and specific to the Prisma docs.

Word choice

Use "you" as the pronoun

Any content should use the second person ("you") to provide a conversational tone. This way, the text and instructions seem to speak directly to the person reading it. Try to avoid using the first person ("I", "we", "let's", and "us").

Using "you" in English is also more accurate than saying "we because typically only one person is reading the tutorial or guide at a time and the person who wrote the tutorial is not actually going through it with them, so "we" would be inaccurate. You might notice that some technical documentation uses third person pronouns and nouns like "they" and "the user", which add more distance and feel colder than the conversational and warm "you" and "your".

When to use "we"

You can use "we" when specifically referring to Prisma. For example:

"We recommend that you share a single instance of PrismaClient across your application.

Avoid words like "easy" and "just"

Avoid using words like "easy", "just" "simple" and "basic" because if users have a hard time completing the task that is supposedly "easy," they will question their abilities. Consider using more specific descriptors; for example, when you say the phrase "deployment is easy," what do you really mean? Is it easy because it takes fewer steps than another option? If so, use the most specific descriptor possible, which in that case would be "this deployment method involves fewer steps than other options."

For even more inclusive docs, avoid phrases that assume a reader’s experience or skill level, like "just deploy it and you’re done" or "for a refresher (referring to a completely different doc that someone may not have read)". Often, rephrasing results in stronger sentences that appeal to a wider range of contexts.

Use inclusive language

When you need to refer to one or more people in third-person, be sure to use inclusive, gender-neutral language if the gender of the person is not explicitly known. Use "they/them/their" instead of "he/him/his" or "she/her/her". Avoid words like "guys"

Avoid emojis, slang, and metaphors

Avoid using emojis or emotions in the docs and idiomatic expressions / slang, or metaphors. Prisma has a global community, and the cultural meaning of an emoji, emoticon, or slang may be different around the world. Use your best judgment! Also, emojis can render differently on different systems.

Avoid Latin terms

For example:

  • et al
  • etc
  • i.e.
  • e.g.

Avoid contractions

For example:

  • You're (use "You are")
  • It'll (use "It will")

Define jargon

Articles should be written with short, clear sentences, and use as little jargon as necessary.

Jargon: (n.) special words or expressions that are used by a particular profession or group and are difficult for others to understand: legal jargon.

All jargon should be defined immediately in plain English. In other words, pretend like your readers have basic coding experience but not necessarily experience with PWAs and the JAMstack (see what happened there? I just used two jargon words that need to be defined); you need to define words that newcomers might have a hard time understanding.

Referring to other parts of the docs

  • Page
  • Section

Technical word choice

Record

Refer to rows in the database as records. For example:

"The following create query creates a single User record."

Do not use:

  • Entry
  • Row
  • Object

Model property

Model property refers to the top-level PrismaClient properties that refer to models:

text
const result = await prisma.user.findMany(...) // user model property
const result = await prisma.post.findMany(...) // post model property

Writing style

Write concisely and avoid long blocks of text

Concise writing communicates the bare minimum without redundancy. Strive to make your writing as short as possible; this practice will often lead to more accurate and specific writing. To avoid large blocks of text:

  • Use shorter paragraphs
  • Use lists
  • Use examples
  • Use bold and emphasis
  • Use tables
  • Use diagrams

Use active voice

Use active voice instead of passive voice. Generally, it’s a more concise and straightforward way to communicate a subject. For example:

  • (passive) The for loop in JavaScript is used by programmers to…
  • (active) Programmers use the for loop in JavaScript to…

Be assertive

Use assertive language.

Good:

  • Use the createMany method to create multiple records in a single transaction
  • You can use nested writes to create a user and that user's posts at the same time

Avoid:

  • This example tries to..
  • You might be able to..
  • You could use..

Hyperlinks should contain the clearest words to indicate where the link will lead you.

md
Read more in the [Prisma docs](https://www.prisma.io/docs/)



Read more in the Prisma docs [here](https://www.prisma.io/docs/)

Indicate when something is optional

When a paragraph or sentence offers an optional path, the beginning of the first sentence should indicate that it’s optional. For example, "if you’d like to learn more about xyz, see our reference guide" is clearer than "Go to the reference guide if you’d like to learn more about xyz."

This method allows people who would not like to learn more about xyz to stop reading the sentence as early as possible. This method also allows people who would like to learn more about xyz to recognize the opportunity to learn quicker instead of accidentally skipping over the paragraph.

Abbreviate terms

If you want to abbreviate a term in your article, write it out fully first, then put the abbreviation in parentheses. After that, you may use the abbreviation going for the rest of the article. For example, "In computer science, an abstract syntax tree (AST) is …".

Embrace redundancy

Meet the user where they are.

Grammar and formatting

Capitalize and spell out proper nouns

Although it can be tempting to use abbreviations like "Postgres" (instead of the official proper noun "PostgreSQL") or not worry about casing when writing "Javascript" (instead of "JavaScript"), we're committed to using the preferred notions of proper nouns. A few common examples are:

  • Node.js (instead of Node or Node.JS)
  • JavaScript and TypeScript (instead of JavaScript and Typescript or JS and TS)
  • PostgreSQL (instead of Postgres or Postgresql)
  • MongoDB (instead of Mongo)
  • GitHub (instead of Github)
  • ...

If you're not sure about the spelling of a certain noun, the official homepage of it typically contains the proper spelling for you to look up.

Titles and headers

  • Use sentence casing for titles and headings: only the initial word is uppercase
  • Use the present participle form of verbs (add -ing - for example: "Configuring the database")
  • Do not use punctuation at the end of the phrase unless a question mark is required
  • Use code for code in headings - this is required by navigation elements

Use tables, bullet lists and numbered lists

Tables and lists are often the most concise way of presenting information. Use the elements whenever they feel appropriate. Here are few guidelines to help decide when to use which:

  • Use bullet lists only when the order of the lists doesn't matter (e.g. an enumeration of the features of a database which don't have an inherent order)
  • Use numbered lists only when the order of the list matters (e.g. when providing step-by-step instructions where one step builds on the previous)
  • Use tables when you're enumerating things that share a number of similar properties/characteristics (e.g. the parameters for an API call which all have a "name", a "type", are required or optional and need a description)

Use italics and bold font

Italics and bold fonts can be a great way to emphasize certain parts of your sentence to the reader. Use bold font more sparsely and only when you want this part to stand out from the entire paragraph (so that it's visible when a reader only "scans" the page instead of properly reading it). Use italics for words that introduce new concepts for the first time.

Use inline code format for paths and file names

For example:

  • "The generated Prisma Client is located in the ./node_modules/.prisma folder by default."
  • "The schema.prisma file is located in..."
  • "To use multiple .env files..."

Use inline code format when referring to strings in text

For example:

"The following query returns all records where the email field is equal to Sarah."

Make lists clear with the Oxford Comma

Use the Oxford Comma except in titles. It is a comma used after the penultimate item in a list of three or more items, before "and" or "or" e.g. an Italian painter, sculptor, and architect. It makes things clearer.

Confusion can happen when you don’t use the Oxford comma.

Prefer US English

For words that have multiple spellings, prefer the US English word over British or Canadian English. For example:

  • "color" over "colour"
  • "behavior" over "behaviour"

Writing code snippets

Introduce all code snippets

Write a short introductory sentence that:

  • Explains what the code snippet is doing
  • Links to reference documentation if applicable

For example:

md
The following [`createMany`](..) query creates several new `User` records:
md
The following [`createMany`](..) query:

- Creates several `User` records
- Creates several nested `Post` records
- Creates several nested `Category` records

Show the result of a query wherever possible

Use the <CodeWithResult> component to show a query and the results of that query.

Use the `highlight` property to highlight

Use the highlight property if you need to highlight your code samples. For example:

text
```prisma highlight=3;normal
generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["orderByRelations"]
}
```

Use inline code only when referring to "code concepts"

TBD

Format code blocks and inline code

Use the following as reference when creating and editing docs: formatting inline code and code blocks.

Emphasize placeholders

Placeholders are a tricky topic in technical documentation and are one of the most common sources of confusion, especially for beginners. To strive for consistency, placeholders in the Prisma docs are:

  • spelled in all-uppercase letters
  • prefixed and suffixed with two underscores
  • using descriptive terms

As an example, consider the following code block where __DATABASE_CONNECTION_URL__ is a placeholder for the PostgreSQL connection URL:

prisma
datasource db {
  provider = "postgresql"
  url      = "__DATABASE_CONNECTION_STRING__"
}

Whenever you're using a placeholder, you should make sure that you directly explain or at least link out to another resource that explains how to obtain a value for the placeholder. You should also explicitly call out that this is a placeholder that needs to get replaced with a "real value" including an example of what that real value might look like:

prisma
datasource db {
  provider = "postgresql"
  url      = "postgresql://opnmyfngbknppm:[email protected]:5432/d50rgmkqi2ipus?schema=hello-prisma2"
}

Use prettier code formatting

TBD

Use expressive variable names

Good:

ts
const getUsers = (...)
const deleteUsers = (...)

Bad:

ts
const results = (...) // Too generic
const foo = (...) // Too vague

Strive for code snippets to be "valid"

TBD

Avoid too many inline comments

TBD

Lists of shell commands

When you need to provide a series of CLI commands as instructions to the reader, don't use a list unless you're providing context for each step:

Bad

  • cd path/to/server
  • docker-compose up -d --build
  • ./node_modules/.bin/sequelize db:migrate or npx sequelize db:migrate
  • ./node_modules/.bin/sequelize db:seed:all or npx sequelize db:seed:all

Better

shell
cd path/to/server
docker-compose up -d --build
./node_modules/.bin/sequelize db:migrate # or `npx sequelize db:migrate`
./node_modules/.bin/sequelize db:seed:all # or `npx sequelize db:seed:all`

or

  1. Navigate into the project directory: cd path/to/server
  2. Start Docker containers: docker-compose up -d --build
  3. Migrate your database schema: ./node_modules/.bin/sequelize db:migrate or npx sequelize db:migrate
  4. Seed the database: ./node_modules/.bin/sequelize db:seed:all or npx sequelize db:seed:all

Don't prepend CLI commands with `$`

Use terminal for CLI commands - this type of code block includes a $:

text
```terminal
npm install prisma
```

For example:

terminal
npm install prisma

npm vs Yarn

Always use npm commands instead of yarn.

Spelling

Hyphens

Hyphens are used according to these rules.

Sometimes there are some terms where it's not clear whether to use a hyphen or not. In order to strive for consistency, we list those terms here as a rule for using them throughout the Prisma documentation.

Spell without hyphen

  • Use case
  • Command line
  • Auto format
  • Type safety

Spell with hyphen

  • Compile-time

Spell as one word

  • Autocomplete

Type-safe and type safe

  • "The code is type safe."
  • "This is type-safe code."

Data source and `datasource`

  • The datasource block
  • "You must regenerate the client when you introduce a new data source"

Boilerplate

The following section contains frequently used phrases or blocks of content that you can re-use:

Introducing a preview feature

md
To enable this feature, add `orderByRelations` to `previewFeatures` in your schema:

```prisma highlight=3;normal
generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["orderByRelations"]
}

Making recommendations

If it is a Prisma recommendation, use:

"We recommend that you share a single instance of PrismaClient across your application."

If it is an industry standard, use:

"It is recommended practice to limit he number of database connections to X."

File: content/600-about/00-whats-new-in-prisma-docs.mdx

title: What's new in Prisma docs metaTitle: "What's new in Prisma docs" metaDescription: "Find out what's new on the Prisma documentation site, including content and site features." toc: false

This page highlights updates to the documentation.
Full release notes for Prisma itself, including breaking changes, are published on GitHub.

The week of June 28th 2021

New Documentation

  • Referential actions guide. Referential actions introduce potentially breaking changes, be sure to read the whole docs page for a full breakdown.

The week of June 7th 2021

New Documentation

  • Getting started guide has had a refactor!
  • The term 'whitelist' has been removed from our documentation, and replaced with 'allowlist'
  • Lots of community PRs merged this past week! We thank you 🙏

The week of May 31st 2021

New documentation

The week of May 24th 2021

New documentation

The week of May 10th 2021

New documentation 📝

The week of May 3rd 2021

New documentation 📝

May 04 2021

Release 🚀

New documentation 📝

April 04 2021

March 16 2021

Prisma Migrate is now Generally Available! 🎉

March 05 2021

New documentation:

March 03 2021

New documentation:

February 16 2021

New documentation:

Video: What's new in Prisma 2.17.0

February 3 2021

New documentation:

Video: What's new in Prisma 2.16.0

January 20 2021

New documentation:

January 5 2021

New documentation:

December 8 2020

New documentation:

November 24 2020

New documentation:

November 10 2020

New documentation:

November 5 2020

  • Documentation site re-design and content re-organization released! 🎉

October 27 2020

New documentation:

October 5 2020

New documentation:

September 15 2020

New documentation:

September 14 2020

New documentation:

September 3 2020

New documentation (2.6.0):

August 24 2020

New documentation:

August 21 2020

New documentation:

August 4 2020

New documentation:

July 28 2020

New documentation:

July 22 2020

New documentation:

July 17 2020

New documentation:

File: content/600-about/01-about-the-docs.mdx

title: 'About the docs' metaTitle: 'About the Prisma documentation' metaDescription: 'This page gives a meta-overview about different topics that are relevant to better understand and navigate the Prisma documentation.'

User and Post are the canonical models that are being used throughout the Prisma docs. This page gives some context on why these have been selected and how to interpret them.

The `User` and `Post` data model

The User and Post models have been selected for the following reasons:

  • These two models do not require domain-specific knowledge.
  • They are also commonly used as an example in the ORM space, making them familiar for users coming from other tools.
  • Having consistent models makes it easier for the reader when learning about different concepts, since there will be less context switching.
  • Less decision making and cognitive overhead for the docs authors. Using the same models reduces decision fatigue and is one less thing to worry about when trying to explain concepts.

We are actively working on adding more schema examples to the docs to provide you with starting points for common data models, such as e-commerce.

Naming conventions for tables and columns

Table names are generally spelled in PascalCase. Column names in camelCase.

Embrace redundancy

Meet the user where they are.

File: content/600-about/05-faq.mdx

title: 'FAQ' metaTitle: 'Prisma FAQs' metaDescription: 'Frequently asked questions (FAQ) about the Prisma tools and their ecosystem.'

Can I still access my database directly (e.g. using raw SQL)?

Yes, Prisma Client provides two methods called $queryRaw and $executeRaw which you can use to send raw SQL to the database. Learn more about these in the docs here.

Note that Prisma currently does not yet support long-running transactions. If your application already needs long-running transactions, you can use Prisma Client alongside other lightweight query builder such as knex.js to perform one-off queries as transaction.

See also: Transaction support in Prisma.

Is Prisma Client an ORM?

ORMs are typically object-oriented mapping layers that map classes to tables. A record is represented as an object that not only carries data but also implements various behaviors for storage, retrieval, serialization and deserialization of its own data, sometimes it also implements business/domain logic. Prisma Client acts more like a query builder returning plain JavaScript objects with a focus on structural typing rather than rich object behavior.

Learn more on the Is Prisma an ORM? page in the docs.

Will Prisma Client support more databases (and other data sources) in the future?

Yes. Prisma Client is based on Prisma's query engine that can connect to any data source that provides a proper connector implementation. There will be built-in connectors such as the current ones for PostgreSQL, MySQL and SQLite.

However, it's also possible to build your own connectors, more documentation on that topic will follow soon.

How can I see the generated queries that Prisma Client sends to my database?

You can view generated SQL queries by providing the log option to the PrismaClient constructor like so:

ts
const prisma = new PrismaClient({
  log: ['query'],
})

Learn more on the Debugging page in the docs.

How do schema migrations work with Prisma Client?

Prisma Client is not opinionated on how exactly you migrate your database schema (e.g. create new tables, alter columns, ...). You can keep your existing migration system and re-introspect your database schema after each schema migration. You can also use Prisma Migrate to run your migrations based on Prisma's declarative data model definition.

Does Prisma Client support GraphQL schema delegation and GraphQL binding?

GraphQL schema delegation connects two GraphQL schemas by passing the info object from a resolver of the first GraphQL schema to a resolver of the second GraphQL schema. Schema delegation also is the foundation for GraphQL binding.

Prisma 1 officially supports both schema delegation and GraphQL binding as it exposes a GraphQL CRUD API through the Prisma server. This API can be used to as the foundation for an application-layer GraphQL API created with GraphQL binding.

With Prisma 2.0, Prisma's query engine doesn't expose a spec-compliant GraphQL endpoint any more, so usage of schema delegation and GraphQL binding with Prisma 2.0 is not supported. To build GraphQL servers with Prisma 2.0, be sure to check out GraphQL Nexus. GraphQL Nexus provides a code-first and type-safe way to build GraphQL servers in a scalable way.

Learn more about how Prisma can be used to build GraphQL servers on the GraphQL page in the docs.

Am I locked-in when using Prisma Migrate? Is it easy to migrate off it?

There's no lock-in when using Prisma Migrate. To stop using Prisma for your migrations, you need to:

  • delete your Prisma schema file
  • delete the migrations directory on your file system
  • drop the _prisma_migrations table in your database/schema

How do I see details about how Prisma migrates my database schema?

Each migration is represented via its own directory on your file system inside a directory called migrations. The name of each directory contains a timestamp so that the order of all migrations in the project history can be maintained.

Each of these migration directories contain a migration.sql file about the respective migration. The status of the migrations is tracked in the _prisma_migrations table in your database/schema. See migrate status.

Since Prisma 2.0 is released, will Prisma 1 still be maintained?

Yes, Prisma 1 will continue to be maintained. However, most Prisma engineering and support resources will go into the development of Prisma 2.0.

There will be no new features developed for Prisma 1.

Note that there will be dedicated tooling and detailed migration guides to help you with the setup.

Where can I get more information about the plans for Prisma?

Check out the Prisma road map for an overview of our priorities. Get involved by creating issues and sharing feedback!

How much does Prisma cost? What is the pricing model for Prisma?

Prisma is open source and using it is free of any charge! In the future, Prisma will offer additional cloud services to facilitate various database- and Prisma-related workflows. Note that these will be optional, Prisma can continue to be used without consuming any commercial services.

File: content/600-about/06-limitations.mdx

title: 'Limitations' metaTitle: 'Limitations' metaDescription: 'This page lists a number of current limitations of Prisma.'

Overview

This page describes features that are currently not supported by Prisma and are not planned to be supported.

Long-running transactions

Databases often offer "long-running transactions" as a feature. A transaction generally refers to a sequence of read/write operations that are guaranteed to either succeed or fail as a whole.

Prisma offers a limited set of transactions in the form of nested writes. There currently is no plan to provide an API to allow a transaction API for long-running transactions.

✍ Read more about How Prisma supports transactions on our blog.

Records must be uniquely identifiable

Prisma currently only supports models that have at least one unique field or combination of fields. In practice, this means that every Prisma model must have either at least one of the following attributes:

  • @id or @@id for a single- or multi-field primary key constraint (max one per model)
  • @unique or @@unique for a single- or multi-field unique constraint

Manual database connection handling

When using Prisma, the database connections are handled on an engine-level. This means they're not exposed to the developer and it's not possible to manually access them.

Prisma Migrate limitations

See: Prisma Migrate limitations and known issues

File: content/600-about/07-roadmap.mdx

title: 'Roadmap' metaTitle: 'Prisma Roadmap – See what we are working on next' metaDescription: 'Want to know what we are up to? Our roadmap provides an overview of our priorities and where we are planning to take Prisma next.'

Our roadmap helps us share our current priorities: what we are currently working on and what we are planning to work on in the near term. This reflects our current plans today, and the content is subject to change at any time. Actual results and plans may differ as a result of changing our product strategy or reacting to demands from our user base.

You can check out the full roadmap here.

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →