Content/init

content/01-getting-started/03-setup-prisma/02-start-from-scratch-sql-migrations.mdx

@@ -18,7 +18,7 @@ In order to successfully complete this guide, you need:
 
 Make sure your have your database [connection URL]() (includes your authentication credentials) at hand!
 
-If you don't have a database server running and only want to explore Prisma, check out the [Quickstart]().
+If you don't have a database server running and only want to explore Prisma, check out the [Quickstart](). Alternatively you can [setup a free PostgreSQL database on Heroku](https://dev.to/prisma/how-to-setup-a-free-postgresql-database-on-heroku-1dc1) and use it in this guide.
 
 ## Create project setup
 

content/03-reference/01-tools-and-interfaces/02-prisma-client/20-database-polyfills.mdx

@@ -0,0 +1,13 @@
+---
+title: "Database polyfills"
+metaTitle: ""
+metaDescription: ""
+---
+
+## Overview
+
+Prisma Client provides features that are typically not achievable with relational databases. These features are referred to as _polyfills_.
+
+- Initializing [ID]() values with `cuid` and `uuid` values (requires [Prisma Migrate]())
+- [Making 1-1-relations required on both sides]()
+- [Implicit many-to-many relations]()

content/03-reference/01-tools-and-interfaces/03-prisma-migrate/01-what-is-prisma-migrate.mdx

@@ -0,0 +1,213 @@
+---
+title: "What is Prisma Migrate"
+metaTitle: ""
+metaDescription: ""
+---
+
+## Overview
+
+Prisma Migrate is a tool that lets you _change your database schema_, e.g. by creating new tables or adding columns to existing tables. These changes are called _schema migrations_. Prisma Migrate is available as part of the [Prisma CLI]() via the `prisma migrate` command.
+
+**Prisma Migrate is currently in an experimental state.** This means that it is not recommended to use Prisma Migrate in production. Instead, you can perform schema migrations using plain SQL or another migration tool of your choice and then bring the changes into your Prisma schema using [introspection]().
+
+## Prisma Migrate vs SQL migrations
+
+Prisma Migrate is a _declarative_ migration system, as opposed to SQL which can be considered _imperative_:
+
+- **SQL (imperative)**: Provide the individual _steps_ to get from the current schema to the desired schema.
+- **Prisma Migrate (delarative)**: Define the desired schema as a [Prisma data model]() (Prisma Migrate takes care of generating the necessary _steps_).
+
+Here's a quick comparison. Assume you have the following scenario:
+
+1. You need to create `User` table to store user information (name, email, ...)
+1. Create two new tables `Post` and `Profile` with foreign keys to `User`
+1. Add a new column with default value to the `Post` table
+
+### SQL 
+
+In SQL, you'd have to send three subsequent SQL statements to account for this scenario:
+
+**1. Create `User` table to store user information (name, email, ...)**
+
+```sql
+CREATE TABLE "User" (
+    id SERIAL PRIMARY KEY,
+    name VARCHAR(255),
+    email VARCHAR(255) NOT NULL
+);
+```
+
+**2. Create two new tables `Post` and `Profile` with foreign keys to `User`**
+
+```sql
+CREATE TABLE "Profile" (
+    id SERIAL PRIMARY KEY,
+    bio TEXT NOT NULL,
+    "user" integer NOT NULL UNIQUE,
+    FOREIGN KEY ("user") REFERENCES "User"(id)
+);
+CREATE TABLE "Post" (
+    id SERIAL PRIMARY KEY,
+    title VARCHAR(255) NOT NULL,
+    author integer NOT NULL,
+    FOREIGN KEY (author) REFERENCES "User"(id)
+);
+```
+
+**3. Add a new column with default value to the `Post` table**
+
+```sql
+ALTER TABLE "Post"
+ADD COLUMN published BOOLEAN DEFAULT false;
+```
+
+### Prisma Migrate
+
+With Prisma Migrate, you write the desired database schema in the form of a [Prisma data model]() inside your [Prisma schema file](). To map the data model to your database schema, you then have to run these two commands:
+
+```
+prisma migrate save --experimental
+prisma migrate up --experimental
+```
+
+The first command _saves_ a new migration to the file system and updates the [`_Migration`]() table. It stores information about the migration in a dedicated directory inside the [`migrations`]() directory. Each migration that is stored has its own `README.md` file which contains detailled information about the migration (e.g. the generated SQL statements which will be executed when you run `prisma migrate up`).
+
+The second command _executes_ the migration against your database.
+
+**1. Create `User` table to store user information (name, email, ...)**
+
+Add a model to your Prisma schema:
+
+```prisma
+model User {
+  id     Int      @id @default(autoincrement())
+  name   String?
+  email  String   @unique
+}
+```
+
+Now run the two commands mentioned above:
+
+```
+prisma migrate save --experimental
+prisma migrate up --experimental
+```
+
+**2. Create two new tables `Post` and `Profile` with foreign keys to `User`**
+
+Add two models with [relation fields]() to your Prisma schema:
+
+```prisma
+model User {
+  id       Int       @id @default(autoincrement())
+  name     String?
+  email    String    @unique
+  posts    Post[]
+  profile  Profile?
+}
+
+model Profile {
+  id   Int    @id @default(autoincrement())
+  bio  String
+  user User
+}
+
+model Post {
+  id      Int     @id @default(autoincrement())
+  title   String
+  author  User
+}
+```
+
+Notice that in addition to the [relation fields which represent the foreign keys](), you also must specify the [virtual relation fields]() on the other side of the relation.
+
+Now run the two commands mentioned above:
+
+```
+prisma migrate save --experimental
+prisma migrate up --experimental
+```
+
+**3. Add a new column with default value to the `Post` table**
+
+Add a [field]() to the `Post` model:
+
+```prisma
+model User {
+  id       Int       @id @default(autoincrement())
+  name     String?
+  email    String    @unique
+  posts    Post[]
+  profile  Profile?
+}
+
+model Profile {
+  id   Int    @id @default(autoincrement())
+  bio  String
+  user User
+}
+
+model Post {
+  id         Int      @id @default(autoincrement())
+  title      String
+  published  Boolean  @default(false)
+  author     User
+}
+```
+
+Now run the two commands mentioned above:
+
+```
+prisma migrate save --experimental
+prisma migrate up --experimental
+```
+
+## Supported operations
+
+The following table shows which SQL operations are currently supported by Prisma Migrate. If an operation is not yet supported, it links to a workaround that uses plain SQL and [introspection]() to enable this feature in Prisma Client.
+
+| Operation                           | SQL                             |        Supported         |
+| :---------------------------------- | :------------------------------ | :----------------------: |
+| Create a new table                  | `CREATE TABLE`                  |            ✔️            |
+| Rename an existing table            | `ALTER TABLE` + `RENAME`        | Not yet ([workaround]()) |
+| Delete an existing table            | `DROP TABLE`                    |            ✔️            |
+| Add a column to an existing table   | `ALTER TABLE` + `ADD COLUMN`    |            ✔️            |
+| Rename an existing column           | `ALTER TABLE` + `RENAME COLUMN` | Not yet ([workaround]()) |
+| Delete an existing column           | `ALTER TABLE` + `DROP COLUMN`   |            ✔️            |
+| Set primary keys ([IDs]())          | `PRIMARY KEY`                   |            ✔️            |
+| Define [relations]() (foreign keys) | `FOREIGN KEY` + `REFERENCES`    |            ✔️            |
+| Make columns [optional/required]()  | `NOT NULL`                      |            ✔️            |
+| Set [unique constraints]()          | `UNIQUE`                        |            ✔️            |
+| Set [default]() values              | `DEFAULT`                       |            ✔️            |
+| Defining [enums]()                  | `ENUM`                          |            ✔️            |
+| Create [indexes]()                  | `CREATE INDEX`                  |            ✔️            |
+| Cascading deletes                   | `ON DELETE`                     | Not yet ([workaround]()) |
+| Cascading updates                   | `ON UPDATE`                     | Not yet ([workaround]()) |
+| Data validation                     | `CHECK`                         | Not yet ([workaround]()) |
+
+Note that this table assumes that the operation is also supported by the underlying database. For example, `ENUM` is not supported in SQLite, this means that you also can't use `enum` using Prisma Migrate.
+
+## Polyfills
+
+Prisma Migrate provides features that are typically not achievable with relational databases. These features are referred to as _polyfills_.
+
+- Initializing [ID]() values with `cuid` and `uuid` values (requires [Prisma Migrate]())
+- [Making 1-1-relations required on both sides]()
+- [Implicit many-to-many relations]()
+
+## Migration history
+
+Prisma Migrate stores the migration history of your project in two places:
+
+- A directory called `migrations` on your file system
+- A table called `_Migrations` in your database
+
+### The `migrations` directory
+
+The `migrations` directory stores information about the migrations that have been or will be executed against your database. You should never make any manual changes to the files in `migrations`, the only way to change the content of this directory should be using the `prisma migrate save` command.
+
+The `migrations` directory should be checked into version control (e.g. Git). 
+
+### The `_Migrations` table
+
+The `_Migrations` table additionally stores information about each migration that was ever executed against the database by Prisma Migrate.