subscriptions Documentation

1. Project Overview & Quickstart (MichalLytek/subscriptions) Copy Chapter

Technical Documentation: MichalLytek/subscriptions

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

subscriptions

Agent Skills & Rules Copy Section

• Discovered 21 agent rule(s) and prompt configurations.

--- METRICS ---

• Files Extracted: 1
• Estimated Token Budget: ~25 tokens
• Canonical Reference: https://codewiki.google/github.com/MichalLytek/subscriptions

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

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

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

TopBlock Copy Chapter

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

<TopBlock>

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

</TopBlock>

Code blocks Copy Chapter

Example:

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

Code:

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

Prisma schema Copy Section

Example:

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:

```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 Copy Section

Example:

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:

```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 Copy Section

Example:

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

Code:

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

Code block without line numbers Copy Section

Example:

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

Code:

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

Code block with highlighted code Copy Section

Example:

async function main() {
  added code

  deleted code

  edited
  code

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

Code:

```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 Copy Chapter

There are 4 icons available:

<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 Copy Chapter

Example:

<TabbedContent tabs={[, ]}>

npm run dev

Code:

<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 Copy Chapter

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

<Subsections depth="3" />

Expand/Collapse section Copy Chapter

Example:

Expand if you want to view more

Here's more!

<details><summary>Expand if you want to view more</summary>

Here's more!

</details>

Button link Copy Chapter

Example:

Button text

Code:

<ButtonLink color="dark" type="primary" href="https://www.prisma.io/docs">
  Button text
</ButtonLink>

Code with output Copy Chapter

Example:

yarn prisma init

$ 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:

<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 Copy Chapter

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:

<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 Copy Chapter

Example:

Code:

<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 Copy Chapter

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

A section Copy Chapter

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 Copy Section

If possible, avoid too many deeply nested subsections.

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

title: Frontmatter metaDescription: "Supported frontmatter variables." Copy Chapter

title Copy Chapter

The <h1> title of the page.

metaTitle Copy Chapter

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

navTitle Copy Chapter

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

metaDescription Copy Chapter

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

staticLink Copy Chapter

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 Copy Chapter

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

toc Copy Chapter

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

toc: true

tocDepth Copy Chapter

Controls the depth of headings to show in the ToC:

tocDepth: 2

Note: Currently limited to 2 levels - h2 and h3

hidePage Copy Chapter

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

hidePage: true

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

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 Copy Chapter

Word choice Copy Chapter

Use "you" as the pronoun Copy Section

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" Copy Section

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 Copy Section

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 Copy Section

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 Copy Section

For example:

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

Avoid contractions Copy Section

For example:

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

Define jargon Copy Section

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 Copy Section

• Page
• Section

Technical word choice Copy Section

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:

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

Writing style Copy Chapter

Write concisely and avoid long blocks of text Copy Section

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 Copy Section

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 Copy Section

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..

Use clear hyperlinks Copy Section

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

<!-- Good -->

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

<!-- Bad -->

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

Indicate when something is optional Copy Section

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 Copy Section

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 Copy Section

Meet the user where they are.

Grammar and formatting Copy Chapter

Capitalize and spell out proper nouns Copy Section

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 Copy Section

• 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 Copy Section

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 Copy Section

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 Copy Section

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 Copy Section

For example:

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

Make lists clear with the Oxford Comma Copy Section

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 Copy Section

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 Copy Chapter

Introduce all code snippets Copy Section

Write a short introductory sentence that:

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

For example:

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

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 Copy Section

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

Use the `highlight` property to highlight Copy Section

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

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

Use inline code only when referring to "code concepts" Copy Section

TBD

Format code blocks and inline code Copy Section

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

Emphasize placeholders Copy Section

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:

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:

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

Use prettier code formatting Copy Section

TBD

Use expressive variable names Copy Section

Good:

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

Bad:

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

Strive for code snippets to be "valid" Copy Section

TBD

Avoid too many inline comments Copy Section

TBD

Lists of shell commands Copy Section

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

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 `$` Copy Section

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

```terminal
npm install prisma
```

For example:

npm install prisma

npm vs Yarn Copy Section

Always use npm commands instead of yarn.

Spelling Copy Chapter

Hyphens Copy Section

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 Copy Chapter

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

Introducing a preview feature Copy Section

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 Copy Section

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 Copy Chapter

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 Copy Chapter

The week of June 28th 2021 Copy Chapter

New Documentation Copy Section

• 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 Copy Chapter

New Documentation Copy Section

• Getting started guide has had a refactor!
  • New, even quicker, Quickstart guide
  • Start from scratch guide now split into easy to digest steps
  • Add to existing project guide now split into easy to digest steps
• 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 Copy Chapter

New documentation Copy Section

• Json field filtering

The week of May 24th 2021 Copy Chapter

New documentation Copy Section

• Note solving @prisma/client did not initialize error on AWS Elastic Beanstalk deployment
• Note clarifying that SQL views workaround doesn't work with Prisma Migrate or introspection
• Community generators
• Troubleshooting running CLI commands in non-interactive environments
• Improved integration testing guide courtesy of community feedback
  • Improved section on deleting all records from all tables
• Updated upgrading to the latest version of Prisma
• Prisma will now run seed files that have a default export, or an export named seed

The week of May 10th 2021 Copy Chapter

New documentation 📝 Copy Section

• Supporting features without a Prisma Schema Language equivalent
• Include unsupported database features with Prisma Migrate
• How to enable extensions for native database functions with Prisma Migrate
• Integration testing guide

The week of May 3rd 2021 Copy Chapter

New documentation 📝 Copy Section

• More in-depth explanation of baselining
• Working with Prisma Migrate as part of a development team
• Error codes are now linkable
• Unit testing guide

May 04 2021 Copy Chapter

Release 🚀 Copy Section

• 2.22.0 documentation

  • db push no longer in preview!
  • Multiple provider support no longer supported

New documentation 📝 Copy Section

• The past month we refactored and expanded the deployment and connection management sections.
• In depth explanation about our choice to use the User and Post data models across the docs

April 04 2021 Copy Chapter

• 2.20.0 documentation

  • push for scalar lists (PostgreSQL only)
  • Relation count
  • nApi preview

March 16 2021 Copy Chapter

Prisma Migrate is now Generally Available! 🎉

• 2.19.0 documentation

  • Prisma Migrate overview
  • Developing with Prisma Migrate
  • Schema prototyping with db push
  • Production troubleshooting
  • Patching / hotfixing your database

March 05 2021 Copy Chapter

New documentation:

• Performance and query optimization guide
• Compound ID examples

March 03 2021 Copy Chapter

New documentation:

• 2.18.0 documentation

February 16 2021 Copy Chapter

New documentation:

• 2.17.0 documentation

  • Native type attributes
  • New types: Bytes, Unsupported, Decimal, BigInt
  • Developing with Prisma Migrate in the cloud

Video: What's new in Prisma 2.17.0 Copy Section

February 3 2021 Copy Chapter

New documentation:

• We now have a Prisma Client API reference section! 🎉

• 2.16.0 documentation

  • createMany
  • orderBy relations

Video: What's new in Prisma 2.16.0 Copy Section

January 20 2021 Copy Chapter

New documentation:

• 2.15.0 documentation

  • Native types with Prisma Migrate
  • Prisma Migrate seeding
  • Scalar list/array filtering
  • Improved count API
  • rejectOnNotFound for findUnique and findFirst

January 5 2021 Copy Chapter

New documentation:

• 2.14.0 documentation

  • Group by

• System requirements for Prisma

December 8 2020 Copy Chapter

New documentation:

• 2.13.0 documentation

  • Prisma Migrate

November 24 2020 Copy Chapter

New documentation:

• 2.12.0 documentation

  • SQL Server native types preview
  • findUnique → findUnique

November 10 2020 Copy Chapter

New documentation:

• 2.11.0 documentation

  • Extended native types support (preview)

November 5 2020 Copy Chapter

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

October 27 2020 Copy Chapter

New documentation:

• 2.10.0 documentation

  • Microsoft SQL Server connector (preview)
  • db push command

October 5 2020 Copy Chapter

New documentation:

• 2.8.0 documentation

  • findFirst

• Advanced middleware examples (soft delete)

September 15 2020 Copy Chapter

New documentation:

• 2.7.0 documentation

  • Where does Prisma look for the schema file (now includes package.json)
  • Support for dotenv-expand

• null vs undefined in Prisma Client

• The prisma version command

September 14 2020 Copy Chapter

New documentation:

• Prisma Client error reference

September 3 2020 Copy Chapter

New documentation (2.6.0):

• Atomic operations on update
• Introspecting with an existing schema

August 24 2020 Copy Chapter

New documentation:

• Prisma Schema API reference section! 🎉
• Multiple data source providers (Now deprecated)

August 21 2020 Copy Chapter

New documentation:

• Case sensitivity with Prisma Client (2.5.0)

August 4 2020 Copy Chapter

New documentation:

• 2.4.0 documentation

  • Sorting by multiple fields
  • Client-level methods (like $on()) now prefixed by $ - versions without $ deprecated but not removed

• Working with scalar lists / scalar arrays

July 28 2020 Copy Chapter

New documentation:

• Aggregations
• connectOrCreate

July 22 2020 Copy Chapter

New documentation:

• Middleware (preview)
• Distinct API (preview)
• .env file locations covered by Prisma Client

July 17 2020 Copy Chapter

New documentation:

• Sorting records with orderBy
• Working with the Json field type
• Documentation changelog added

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

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.' Copy Chapter

The `User` and `Post` data model Copy Chapter

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 Copy Chapter

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

Embrace redundancy Copy Chapter

Meet the user where they are.

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

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

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

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? Copy Chapter

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? Copy Chapter

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? Copy Chapter

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

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

Learn more on the Debugging page in the docs.

How do schema migrations work with Prisma Client? Copy Chapter

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? Copy Chapter

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? Copy Chapter

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? Copy Chapter

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? Copy Chapter

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? Copy Chapter

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? Copy Chapter

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 Copy Chapter

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

Overview Copy Chapter

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

Long-running transactions Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

See: Prisma Migrate limitations and known issues

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

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.' Copy Chapter

File: content/600-about/08-releases.mdx Copy Chapter

title: 'Releases and maturity levels' metaTitle: 'Releases and maturity levels' metaDescription: 'Learn about the release process, versioning, and maturity of Prisma components and how to deal with breaking changes that might happen throughout releases.' Copy Chapter

Releases Copy Chapter

Prisma releases typically happen every two weeks. Note that this is not a hard rule, releases might be postponed for internal reasons.

Product maturity levels Copy Chapter

A release can include products or features at different maturity levels. Maturity level describes a product or feature's completeness, and what users can expect in terms of breaking changes.

Note: As of version 2.13.0, 'Experimental' is no longer part of the product maturity scale.

Early Access Copy Section

If a feature or product is Early Access:

• We have validated a problem and are considering a solution to it, but are not certain whether that solution is complete or a perfect fit.
• We want to gather more feedback and adjust the solution as necessary, knowing that users are prepared for significant breaking changes

Not recommended for production.

Preview Copy Section

If a feature or product is a Preview:

• We have validated the feature or product in terms of direction and surface.
• Users can count on the feature or product and associated API to be mostly stable, unless stated otherwise in the release notes and documentation.
• There are no significant known issues, although smaller bugs may exist.
• We welcome feedback on these to make the solution stable as quickly as possible.

Previews are typically available behind a feature flag or require some form of opt-in (for example, by providing a --preview-feature flag in the CLI or adding them to a previewFeatures property in the generator block for Prisma Client in your Prisma schema).

Not recommended for production.

See also: All currently available Preview features.

Generally Available (GA) Copy Section

If a feature or product is Generally Available:

• The solution has been tested for some time and we received enough feedback to consider it stable and ready for production use.
• There should be no bugs in 99% of cases (completely bug-free software cannot be guaranteed)

Versioning Copy Chapter

Prisma's approach for versioning is inspired by Semantic Versioning (SemVer) but doesn't fully adhere to it.

Prisma vs SemVer Copy Section

How does SemVer versioning work?

Semantic Versioning (SemVer) uses the following rules for version upgrade (quoted from the SemVer spec):

Given a version number MAJOR.MINOR.PATCH, increment the:

1. MAJOR version when you make incompatible API changes,
2. MINOR version when you add functionality in a backwards compatible manner, and
3. PATCH version when you make backwards compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

How does Prisma versioning work?

While Prisma releases follow the format of the Semantic Versioning (SemVer) specification, it does not follow the rule that MINOR version updates must not have incompatible API changes (i.e. breaking changes). This means that there might be breaking changes in any 2.X release.

Given a version number MAJOR.MINOR.PATCH, Prisma's version number is incremented as follows:

1. MAJOR version is incremented when major product updates (likely with breaking changes) are released,
2. MINOR version is incremented for minor product updates (may have breaking API changes) are released, and
3. PATCH version functionality is added or bugs are fixed (backwards compatible).

Why does Prisma not follow SemVer?

Prisma is one of many developer tools that doesn't follow the SemVer specification. The main reason is that Prisma has a huge developer surface made up by several tools (the Prisma CLI, Prisma Client, Prisma Migrate, Prisma Studio, ...). Therefore, a breaking change in one tool might not affect usage of another tool, so incrementing the major version number for the tools that are not affected might not be justified.

File: content/600-about/09-example-projects.mdx Copy Chapter

title: 'Example projects' metaTitle: 'Ready-to-run examples for various Prisma use cases' metaDescription: 'Real-world & production-ready example projects with Prisma. Here are a number of open source projects that demonstrate usage of Prisma in real world applications.' Copy Chapter

Real-world & production-ready example projects with Prisma Copy Chapter

Here are a number of open source projects that demonstrate usage of Prisma in real world applications. Feel free to submit a PR to add your own production application if it is open source.

• Backend for a real world grading application (incl video and written tutorials)
• Tottem – Fullstack app for "social library management" (based on Next.js)

Ready-to-run example projects Copy Chapter

You can find a number of ready-to-run example projects that demonstrate usage of Prisma in various use cases in the prisma-examples repository.

TypeScript Copy Section

Fullstack

Backend only

JavaScript (Node.js) Copy Section

Fullstack

Backend only

File: content/600-about/index.mdx Copy Chapter

title: 'About' metaTitle: 'About' metaDescription: 'About' toc: false hidePage: false Copy Chapter

In this section Copy Chapter