|
| 1 | +# Next.js Example |
| 2 | + |
| 3 | +This example shows how to implement a simple web app using [Next.js](https://nextjs.org/) and [Prisma Client](https://www.prisma.io/docs/concepts/components/prisma-client). The example uses an SQLite database file with some initial dummy data. The example was bootstrapped using the Next.js CLI command `create-next-app`. |
| 4 | + |
| 5 | +## Getting started |
| 6 | + |
| 7 | +### 1. Fill out .env file |
| 8 | + |
| 9 | +If you just want to run the app locally, rename `.env.local.example` to `.env.local` and fill in the values. |
| 10 | + |
| 11 | +#### 1.1 Create a Prisma Postgres instance |
| 12 | + |
| 13 | +Go to [the Console](https://console.prisma.io) and create a new Prisma Postgres instance. Use the `DATABASE_URL` and `PULSE_API_KEY` values from the new instance to fill out the `.env.local` file. |
| 14 | + |
| 15 | +#### 1.2 Create a GitHub OAuth app |
| 16 | + |
| 17 | +Go to [the GitHub Developer Settings](https://github.com/settings/developers) and create a new OAuth app. Use the `AUTH_GITHUB_ID` and `AUTH_GITHUB_SECRET` values from the new app to fill out the `.env.local` file. |
| 18 | + |
| 19 | +#### 1.3 Fill out Auth.js secrets |
| 20 | + |
| 21 | +Run `npx auth secret` to generate a new `AUTH_SECRET` value. Fill out the `.env.local` file with the new value. |
| 22 | + |
| 23 | +### 2. Install dependencies |
| 24 | + |
| 25 | +Install npm dependencies: |
| 26 | + |
| 27 | +``` |
| 28 | +npm install |
| 29 | +``` |
| 30 | + |
| 31 | +### 3. Create and seed the database |
| 32 | + |
| 33 | +Run the following command to create your database. This also creates the needed tables that are defined in [`prisma/schema.prisma`](./prisma/schema.prisma): |
| 34 | + |
| 35 | +``` |
| 36 | +npx prisma migrate dev --name init |
| 37 | +``` |
| 38 | + |
| 39 | +When `npx prisma migrate dev` is executed against a newly created database, seeding is also triggered. The seed file in [`prisma/seed.ts`](./prisma/seed.ts) will be executed and your database will be populated with the sample data. |
| 40 | + |
| 41 | +**If you switched to Prisma Postgres in the previous step**, you need to trigger seeding manually (because Prisma Postgres already created an empty database instance for you, so seeding isn't triggered): |
| 42 | + |
| 43 | +``` |
| 44 | +npx prisma db seed |
| 45 | +``` |
| 46 | + |
| 47 | +### 3. Start the Next.js server |
| 48 | + |
| 49 | +``` |
| 50 | +npm run dev |
| 51 | +``` |
| 52 | + |
| 53 | +The server is now running on `http://localhost:3000`. You can now view pages, e.g. [`http://localhost:3000/posts`](http://localhost:3000/posts). |
| 54 | + |
| 55 | +## Evolving the app |
| 56 | + |
| 57 | +Evolving the application typically requires two steps: |
| 58 | + |
| 59 | +1. Migrate your database using Prisma Migrate |
| 60 | +1. Update your application code |
| 61 | + |
| 62 | +For the following example scenario, assume you want to add a "profile" feature to the app where users can create a profile and write a short bio about themselves. |
| 63 | + |
| 64 | +### 1. Migrate your database using Prisma Migrate |
| 65 | + |
| 66 | +The first step is to add a new table, e.g. called `Profile`, to the database. You can do this by adding a new model to your [Prisma schema file](./prisma/schema.prisma) file and then running a migration afterwards: |
| 67 | + |
| 68 | +```diff |
| 69 | +// ./prisma/schema.prisma |
| 70 | + |
| 71 | +model User { |
| 72 | + id Int @default(autoincrement()) @id |
| 73 | + name String? |
| 74 | + email String @unique |
| 75 | + posts Post[] |
| 76 | ++ profile Profile? |
| 77 | +} |
| 78 | + |
| 79 | +model Post { |
| 80 | + id Int @id @default(autoincrement()) |
| 81 | + createdAt DateTime @default(now()) |
| 82 | + updatedAt DateTime @updatedAt |
| 83 | + title String |
| 84 | + content String? |
| 85 | + published Boolean @default(false) |
| 86 | + viewCount Int @default(0) |
| 87 | + author User? @relation(fields: [authorId], references: [id]) |
| 88 | + authorId Int? |
| 89 | +} |
| 90 | + |
| 91 | ++model Profile { |
| 92 | ++ id Int @default(autoincrement()) @id |
| 93 | ++ bio String? |
| 94 | ++ user User @relation(fields: [userId], references: [id]) |
| 95 | ++ userId Int @unique |
| 96 | ++} |
| 97 | +``` |
| 98 | + |
| 99 | +Once you've updated your data model, you can execute the changes against your database with the following command: |
| 100 | + |
| 101 | +``` |
| 102 | +npx prisma migrate dev --name add-profile |
| 103 | +``` |
| 104 | + |
| 105 | +This adds another migration to the `prisma/migrations` directory and creates the new `Profile` table in the database. |
| 106 | + |
| 107 | +### 2. Update your application code |
| 108 | + |
| 109 | +You can now use your `PrismaClient` instance to perform operations against the new `Profile` table. Those operations can be used to implement new pages in the app. |
| 110 | + |
| 111 | +## Switch to another database (e.g. PostgreSQL, MySQL, SQL Server, MongoDB) |
| 112 | + |
| 113 | +If you want to try this example with another database than SQLite, you can adjust the the database connection in [`prisma/schema.prisma`](./prisma/schema.prisma) by reconfiguring the `datasource` block. |
| 114 | + |
| 115 | +Learn more about the different connection configurations in the [docs](https://www.prisma.io/docs/reference/database-reference/connection-urls). |
| 116 | + |
| 117 | +<details><summary>Expand for an overview of example configurations with different databases</summary> |
| 118 | + |
| 119 | +### PostgreSQL |
| 120 | + |
| 121 | +For PostgreSQL, the connection URL has the following structure: |
| 122 | + |
| 123 | +```prisma |
| 124 | +datasource db { |
| 125 | + provider = "postgresql" |
| 126 | + url = "postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=SCHEMA" |
| 127 | +} |
| 128 | +``` |
| 129 | + |
| 130 | +Here is an example connection string with a local PostgreSQL database: |
| 131 | + |
| 132 | +```prisma |
| 133 | +datasource db { |
| 134 | + provider = "postgresql" |
| 135 | + url = "postgresql://janedoe:mypassword@localhost:5432/notesapi?schema=public" |
| 136 | +} |
| 137 | +``` |
| 138 | + |
| 139 | +### MySQL |
| 140 | + |
| 141 | +For MySQL, the connection URL has the following structure: |
| 142 | + |
| 143 | +```prisma |
| 144 | +datasource db { |
| 145 | + provider = "mysql" |
| 146 | + url = "mysql://USER:PASSWORD@HOST:PORT/DATABASE" |
| 147 | +} |
| 148 | +``` |
| 149 | + |
| 150 | +Here is an example connection string with a local MySQL database: |
| 151 | + |
| 152 | +```prisma |
| 153 | +datasource db { |
| 154 | + provider = "mysql" |
| 155 | + url = "mysql://janedoe:mypassword@localhost:3306/notesapi" |
| 156 | +} |
| 157 | +``` |
| 158 | + |
| 159 | +### Microsoft SQL Server |
| 160 | + |
| 161 | +Here is an example connection string with a local Microsoft SQL Server database: |
| 162 | + |
| 163 | +```prisma |
| 164 | +datasource db { |
| 165 | + provider = "sqlserver" |
| 166 | + url = "sqlserver://localhost:1433;initial catalog=sample;user=sa;password=mypassword;" |
| 167 | +} |
| 168 | +``` |
| 169 | + |
| 170 | +### MongoDB |
| 171 | + |
| 172 | +Here is an example connection string with a local MongoDB database: |
| 173 | + |
| 174 | +```prisma |
| 175 | +datasource db { |
| 176 | + provider = "mongodb" |
| 177 | + url = "mongodb://USERNAME:PASSWORD@HOST/DATABASE?authSource=admin&retryWrites=true&w=majority" |
| 178 | +} |
| 179 | +``` |
| 180 | + |
| 181 | +</details> |
| 182 | + |
| 183 | +## Next steps |
| 184 | + |
| 185 | +- Check out the [Prisma docs](https://www.prisma.io/docs) |
| 186 | +- Share your feedback on the [Prisma Discord](https://pris.ly/discord/) |
| 187 | +- Create issues and ask questions on [GitHub](https://github.com/prisma/prisma/) |
0 commit comments