1 | <p align="center"><a href="https://www.prisma.io"><img src="https://i.imgur.com/QgwDieO.png" alt="Prisma" height="230px"></a></p>
|
2 |
|
3 | [Website](https://www.prisma.io) • [Docs](https://www.prisma.io/docs/) • [Examples](https://github.com/prisma/prisma-examples/) • [Blog](https://www.prisma.io/blog) • [Forum](https://www.prisma.io/forum) • [Slack](https://slack.prisma.io/) • [Twitter](https://twitter.com/prisma) • [OSS](https://oss.prisma.io/) • [Learn](https://www.howtographql.com)
|
4 |
|
5 | [![CircleCI](https://circleci.com/gh/prisma/prisma.svg?style=shield)](https://circleci.com/gh/prisma/prisma) [![Slack Status](https://slack.prisma.io/badge.svg)](https://slack.prisma.io) [![Join the community on Spectrum](https://withspectrum.github.io/badge/badge.svg)](https://spectrum.chat/prisma)
|
6 |
|
7 | Prisma replaces traditional ORMs and simplifies database workflows:
|
8 |
|
9 | - _Access_: **Type-safe database access with the auto-generated Prisma client** (in [JavaScript](https://www.prisma.io/client/client-javscript/), [TypeScript](https://www.prisma.io/client/client-typescript/), [Go](https://www.prisma.io/client/client-go/))
|
10 | - _Migrate_: **Declarative data modelling and migrations** (optional)
|
11 | - _Manage_: **Visual data management with Prisma Admin**
|
12 |
|
13 | It is used to build **GraphQL, REST, gRPC APIs** and more. Prisma [currently supports](#database-connectors) MySQL, PostgreSQL, MongoDB.
|
14 |
|
15 | Try a Prisma example online with CodeSandbox:
|
16 |
|
17 | [![Prisma Client Demo](https://svgshare.com/i/AVY.svg)](https://codesandbox.io/s/github/prisma-csb/prisma-client-demo-ts) [![GraphQL API](https://svgshare.com/i/AVX.svg)](https://codesandbox.io/s/github/prisma-csb/graphql-example-ts) [![REST API](https://svgshare.com/i/AY0.svg)](https://codesandbox.io/s/github/prisma-csb/rest-example-ts?initialpath=/feed)
|
18 |
|
19 | ## Contents
|
20 |
|
21 | - [Quickstart](#quickstart)
|
22 | - [Examples](#examples)
|
23 | - [Database Connectors](#database-connectors)
|
24 | - [Community](#community)
|
25 | - [Contributing](#contributing)
|
26 |
|
27 | ## Quickstart
|
28 |
|
29 | Get started with Prisma from scratch (or [use your existing database](https://www.prisma.io/docs/-t003/)):
|
30 |
|
31 | #### 1. Install Prisma via Homebrew
|
32 |
|
33 | ```
|
34 | brew tap prisma/prisma
|
35 | brew install prisma
|
36 | ```
|
37 |
|
38 | <Details>
|
39 | <Summary><b>Alternative</b>: Install with NPM or Yarn</Summary>
|
40 |
|
41 | ```
|
42 | npm install -g prisma
|
43 | # or
|
44 | yarn global add prisma
|
45 | ```
|
46 | </Details>
|
47 |
|
48 | #### 2. Connect Prisma to a database
|
49 |
|
50 | To setup Prisma, you need to have [Docker](https://www.docker.com) installed. Run the following command to get started with Prisma:
|
51 |
|
52 | ```
|
53 | prisma init hello-world
|
54 | ```
|
55 |
|
56 | The interactive CLI wizard now helps you with the required setup:
|
57 |
|
58 | - Select **Create new database** (you can also use an [existing database](https://www.prisma.io/docs/-t003/) or a hosted [demo database](https://www.prisma.io/docs/-t001/))
|
59 | - Select the database type: **MySQL** or **PostgreSQL**
|
60 | - Select the language for the generated Prisma client: **TypeScript**, **Flow**, **JavaScript** or **Go**
|
61 |
|
62 | Once the wizard has terminated, run the following commands to setup Prisma:
|
63 |
|
64 | ```
|
65 | cd hello-world
|
66 | docker-compose up -d
|
67 | ```
|
68 |
|
69 | #### 3. Define your datamodel
|
70 |
|
71 | Edit `datamodel.prisma` to define your datamodel using [SDL](https://www.prisma.io/blog/graphql-sdl-schema-definition-language-6755bcb9ce51/) syntax. Each model is mapped to a table in your database schema:
|
72 |
|
73 | ```graphql
|
74 | type User {
|
75 | id: ID! @id
|
76 | email: String @unique
|
77 | name: String!
|
78 | posts: [Post!]!
|
79 | }
|
80 |
|
81 | type Post {
|
82 | id: ID! @id
|
83 | title: String!
|
84 | published: Boolean! @default(value: false)
|
85 | author: User
|
86 | }
|
87 | ```
|
88 |
|
89 | #### 4. Deploy datamodel & migrate database
|
90 |
|
91 | To deploy your Prisma API, run the following command:
|
92 |
|
93 | ```
|
94 | prisma deploy
|
95 | ```
|
96 |
|
97 | The Prisma API is deployed based on the datamodel and exposes CRUD & realtime operations for each model in that file.
|
98 |
|
99 | #### 5. Use the Prisma client (Node.js)
|
100 |
|
101 | The Prisma client connects to the Prisma API and lets you perform read and write operations against your database. This section explains how to use the Prisma client from **Node.js**.
|
102 |
|
103 | Inside the `hello-world` directory, install the `prisma-client-lib` dependency:
|
104 |
|
105 | ```
|
106 | npm install --save prisma-client-lib
|
107 | ```
|
108 |
|
109 | To generate the Prisma client, run the following command:
|
110 |
|
111 | ```
|
112 | prisma generate
|
113 | ```
|
114 |
|
115 | Create a new Node script inside the `hello-world` directory:
|
116 |
|
117 | ```
|
118 | touch index.js
|
119 | ```
|
120 |
|
121 | Add the following code to it:
|
122 |
|
123 | ```js
|
124 | const { prisma } = require('./generated/prisma-client')
|
125 |
|
126 | // A `main` function so that we can use async/await
|
127 | async function main() {
|
128 | // Create a new user with a new post
|
129 | const newUser = await prisma.createUser({
|
130 | name: 'Alice',
|
131 | posts: {
|
132 | create: { title: 'The data layer for modern apps' }
|
133 | }
|
134 | })
|
135 | console.log(`Created new user: ${newUser.name} (ID: ${newUser.id})`)
|
136 |
|
137 | // Read all users from the database and print them to the console
|
138 | const allUsers = await prisma.users()
|
139 | console.log(allUsers)
|
140 |
|
141 | // Read all posts from the database and print them to the console
|
142 | const allPosts = await prisma.posts()
|
143 | console.log(allPosts)
|
144 | }
|
145 |
|
146 | main().catch(e => console.error(e))
|
147 | ```
|
148 |
|
149 | Finally, run the code using the following command:
|
150 |
|
151 | ```
|
152 | node index.js
|
153 | ```
|
154 |
|
155 | <details><summary><b>See more API operations</b></summary>
|
156 | <p>
|
157 |
|
158 | ```js
|
159 | const usersCalledAlice = await prisma
|
160 | .users({
|
161 | where: {
|
162 | name: "Alice"
|
163 | }
|
164 | })
|
165 | ```
|
166 |
|
167 | ```js
|
168 | // replace the __USER_ID__ placeholder with an actual user ID
|
169 | const updatedUser = await prisma
|
170 | .updateUser({
|
171 | where: { id: "__USER_ID__" },
|
172 | data: { email: "alice@prisma.io" }
|
173 | })
|
174 | ```
|
175 |
|
176 | ```js
|
177 | // replace the __USER_ID__ placeholder with an actual user ID
|
178 | const deletedUser = await prisma
|
179 | .deleteUser({ id: "__USER_ID__" })
|
180 | ```
|
181 |
|
182 | ```js
|
183 | const postsByAuthor = await prisma
|
184 | .user({ email: "alice@prisma.io" })
|
185 | .posts()
|
186 | ```
|
187 |
|
188 | </p>
|
189 | </details>
|
190 |
|
191 |
|
192 | #### 6. Next steps
|
193 |
|
194 | Here is what you can do next:
|
195 |
|
196 | - [Build an app with Prisma client](https://www.prisma.io/docs/-t201/)
|
197 | - [Check out some examples](#examples)
|
198 | - [Read more about how Prisma works](https://www.prisma.io/docs/-j9ff/)
|
199 |
|
200 | ## Examples
|
201 |
|
202 | #### TypeScript
|
203 |
|
204 | | Demo | Description |
|
205 | |:------|:----------|
|
206 | | [`script`](https://github.com/prisma/prisma-examples/tree/master/typescript/script) | Simple usage of Prisma client in script |
|
207 | | [`graphql`](https://github.com/prisma/prisma-examples/tree/master/typescript/graphql) | Simple GraphQL server based on [`graphql-yoga`](https://github.com/prisma/graphql-yoga) |
|
208 | | [`graphql-apollo-server`](https://github.com/prisma/prisma-examples/tree/master/typescript/graphql-apollo-server) | Simple GraphQL server based on [`apollo-server`](https://www.apollographql.com/docs/apollo-server/) |
|
209 | | [`graphql-crud`](https://github.com/prisma/prisma-examples/tree/master/typescript/graphql-crud) | GraphQL server with full CRUD API |
|
210 | | [`graphql-auth`](https://github.com/prisma/prisma-examples/tree/master/typescript/graphql-auth) | GraphQL server with email-password authentication & permissions |
|
211 | | [`graphql-subscriptions`](https://github.com/prisma/prisma-examples/tree/master/typescript/graphql-subscriptions) | GraphQL server with realtime subscriptions |
|
212 | | [`rest-express`](https://github.com/prisma/prisma-examples/tree/master/typescript/rest-express) | Simple REST API with Express.JS |
|
213 | | [`grpc`](https://github.com/prisma/prisma-examples/tree/master/typescript/grpc) | Simple gRPC API |
|
214 | | [`docker-mongodb`](https://github.com/prisma/prisma-examples/tree/master/typescript/docker-mongodb) | Set up Prisma locally with MongoDB |
|
215 | | [`docker-mysql`](https://github.com/prisma/prisma-examples/tree/master/typescript/docker-mysql) | Set up Prisma locally with MySQL |
|
216 | | [`docker-postgres`](https://github.com/prisma/prisma-examples/tree/master/typescript/docker-postgres) | Set up Prisma locally with PostgreSQL |
|
217 | | [`cli-app`](https://github.com/prisma/prisma-examples/tree/master/typescript/cli-app) | Simple CLI TODO list app |
|
218 |
|
219 | #### Node.js
|
220 |
|
221 | | Demo | Description |
|
222 | |:------|:----------|
|
223 | | [`script`](https://github.com/prisma/prisma-examples/tree/master/node/script) | Simple usage of Prisma client in script |
|
224 | | [`graphql`](https://github.com/prisma/prisma-examples/tree/master/node/graphql) | Simple GraphQL server |
|
225 | | [`graphql-auth`](https://github.com/prisma/prisma-examples/tree/master/node/graphql-auth) | GraphQL server with email-password authentication & permissions |
|
226 | | [`graphql-subscriptions`](https://github.com/prisma/prisma-examples/tree/master/node/graphql-subscriptions) | GraphQL server with realtime subscriptions |
|
227 | | [`rest-express`](https://github.com/prisma/prisma-examples/tree/master/node/rest-express) | Simple REST API with Express.JS |
|
228 | | [`grpc`](https://github.com/prisma/prisma-examples/tree/master/node/grpc) | Simple gRPC API |
|
229 | | [`docker-mongodb`](https://github.com/prisma/prisma-examples/tree/master/node/docker-mongodb) | Set up Prisma locally with MongoDB |
|
230 | | [`docker-mysql`](https://github.com/prisma/prisma-examples/tree/master/node/docker-mysql) | Set up Prisma locally with MySQL |
|
231 | | [`docker-postgres`](https://github.com/prisma/prisma-examples/tree/master/node/docker-postgres) | Set up Prisma locally with PostgreSQL |
|
232 | | [`cli-app`](https://github.com/prisma/prisma-examples/tree/master/node/cli-app) | Simple CLI TODO list app |
|
233 |
|
234 | #### Golang
|
235 |
|
236 | | Demo | Description |
|
237 | |:------|:----------|
|
238 | | [`cli-app`](https://github.com/prisma/prisma-examples/tree/master/go/cli-app) | Simple CLI TODO list app |
|
239 | | [`graphql`](https://github.com/prisma/prisma-examples/tree/master/go/graphql) | Simple GraphQL server |
|
240 | | [`http-mux`](https://github.com/prisma/prisma-examples/tree/master/go/http-mux) | Simple REST API with [gorilla/mux](https://github.com/gorilla/mux) |
|
241 | | [`rest-gin`](https://github.com/prisma/prisma-examples/tree/master/go/rest-gin) | Simple REST API with [Gin](https://github.com/gin-gonic/gin) |
|
242 | | [`script`](https://github.com/prisma/prisma-examples/tree/master/go/script) | Simple usage of Prisma client in script |
|
243 |
|
244 | #### Flow
|
245 |
|
246 | | Demo | Description |
|
247 | |:------|:----------|
|
248 | | [`graphql`](https://github.com/prisma/prisma-examples/tree/master/flow/graphql) | Simple GraphQL server |
|
249 | | [`script`](https://github.com/prisma/prisma-examples/tree/master/flow/script) | Simple usage of Prisma client in script |
|
250 |
|
251 | ## Database Connectors
|
252 |
|
253 | [Database connectors](https://github.com/prisma/prisma/issues/1751) provide the link between Prisma and the underlying database.
|
254 |
|
255 | You can connect the following databases to Prisma already:
|
256 |
|
257 | - MySQL
|
258 | - PostgreSQL
|
259 | - MongoDB
|
260 |
|
261 | ### Upcoming Connectors
|
262 |
|
263 | If you are interested to participate in the preview for one of the following connectors, please reach out in our [Slack](https://slack.prisma.io).
|
264 |
|
265 | - [Elastic Search](https://github.com/prisma/prisma/issues/1665)
|
266 | - [MS SQL](https://github.com/prisma/prisma/issues/1642)
|
267 | - [Oracle](https://github.com/prisma/prisma/issues/1644)
|
268 | - [ArangoDB](https://github.com/prisma/prisma/issues/1645)
|
269 | - [Neo4j](https://github.com/prisma/prisma/issues/1646)
|
270 | - [Druid](https://github.com/prisma/prisma/issues/1647)
|
271 | - [Dgraph](https://github.com/prisma/prisma/issues/1648)
|
272 | - [DynamoDB](https://github.com/prisma/prisma/issues/1655)
|
273 | - [Cloud Firestore](https://github.com/prisma/prisma/issues/1660)
|
274 | - [CockroachDB](https://github.com/prisma/prisma/issues/1705)
|
275 | - [Cassandra](https://github.com/prisma/prisma/issues/1750)
|
276 | - [Redis](https://github.com/prisma/prisma/issues/1722)
|
277 | - [AWS Neptune](https://github.com/prisma/prisma/issues/1752)
|
278 | - [CosmosDB](https://github.com/prisma/prisma/issues/1663)
|
279 | - [Influx](https://github.com/prisma/prisma/issues/1857)
|
280 |
|
281 | Join the discussion or contribute to influence which we'll work on next!
|
282 |
|
283 | ## Community
|
284 |
|
285 | Prisma has a [community](https://www.prisma.io/community) of thousands of amazing developers and contributors. Welcome, please join us! 👋
|
286 |
|
287 | > Meet the Prisma community in person and learn about modern application development and database best practices at [**Prisma Day**](https://www.prisma.io/day/) (Berlin, June 19).
|
288 |
|
289 | ### Channels
|
290 |
|
291 | - [Forum](https://www.prisma.io/forum)
|
292 | - [Spectrum](https://spectrum.chat/prisma)
|
293 | - [Slack](https://slack.prisma.io/)
|
294 | - [Twitter](https://twitter.com/prisma)
|
295 | - [Facebook](https://www.facebook.com/prisma.io)
|
296 | - [Meetup](https://www.meetup.com/graphql-berlin)
|
297 | - [GraphQL Conf](https://www.graphqlconf.org/)
|
298 | - [Email](mailto:hello@prisma.io)
|
299 |
|
300 | ### Resources
|
301 |
|
302 | - [Chinese translation of the Prisma docs](https://prisma.1wire.com/) (Thanks to [Victor Kang](https://github.com/Victorkangsh))
|
303 | - [Awesome Prisma](https://github.com/catalinmiron/awesome-prisma) (Thanks to [Catalin Miron](https://github.com/catalinmiron))
|
304 |
|
305 | ## Contributing
|
306 |
|
307 | Contributions are **welcome and extremely helpful** 🙌
|
308 | Please refer [to the contribution guide](https://github.com/prisma/prisma/blob/master/CONTRIBUTING.md) for more information.
|
309 |
|
310 | Releases are separated into three _channels_: **alpha**, **beta** and **stable**. You can learn more about these three channels and Prisma's release process [here](https://www.prisma.io/blog/improving-prismas-release-process-yaey8deiwaex/).
|
311 |
|
312 | <p align="center"><a href="https://oss.prisma.io"><img src="https://imgur.com/IMU2ERq.png" alt="Prisma" height="170px"></a></p>
|