Switch branches/tags
Find file History
Latest commit 4255f94 Oct 24, 2018

README.md

Prisma

WebsiteDocsBlogForumSlackTwitterOSSLearn

CircleCI Slack Status npm version

Prisma is a performant open-source GraphQL ORM-like layer doing the heavy lifting in your GraphQL server. It turns your database into a GraphQL API which can be consumed by your resolvers via GraphQL bindings.

Prisma's auto-generated GraphQL API provides powerful abstractions and modular building blocks to develop flexible and scalable GraphQL backends:

  • Type-safe API including filters, aggregations, pagination and transactions.
  • Data modeling & migrations with declarative GraphQL SDL.
  • Realtime API using GraphQL subscriptions.
  • Advanced API composition using GraphQL bindings and schema stitching.
  • Works with all frontend frameworks like React, Vue.js, Angular.

Contents

Quickstart

Watch this 3-min tutorial or follow the steps below to get started with Prisma.

1. Install the CLI via NPM

npm install -g prisma

2. Create a new Prisma service

Run the following command to create the files you need for a new Prisma service.

prisma init hello-world

Then select the Demo server (hosted in Prisma Cloud) and follow the instructions of the interactive CLI prompt.

Alternative: Setup Prisma with your own database.

Instead of using a Demo server, you can also setup a Prisma server that is connected to your own database. Note that this requires Docker.

To do so, run prisma init as shown above and follow the interactive CLI prompts to choose your own database setup:

  • Create a new database
  • Connect an existing database

Once the command has finished, you need to run docker-compose up -d to start the Prisma server.

3. Define your data model

Edit datamodel.prisma to define your data model using GraphQL SDL:

type Tweet {
  id: ID! @unique
  createdAt: DateTime!
  text: String!
  owner: User!
}

type User {
  id: ID! @unique
  handle: String! @unique
  name: String!
  tweets: [Tweet!]!
}

4. Deploy your Prisma service

To deploy your service, run the following command:

prisma deploy

5. Explore the API in a Playground

Run the following command to open a GraphQL Playground and start sending queries and mutations:

prisma playground
I don't know what queries and mutations I can send.

Create a new user:

mutation {
  createUser(
    data: {
      name: "Alice"
      handle: "alice"
    }
  ) {
    id
  }
}

Query all users and their tweets:

query {
  users {
    id
    name
    tweets {
      id
      createdAt
      text
    }
  }
}

Create a new tweet for a user:

Replace the __USER_ID__ placeholder with the id of an actual User

mutation {
  createTweet(
    data: {
      text: "Prisma makes building GraphQL servers fun & easy"
      owner: {
        connect: {
          id: "__USER_ID__"
        }
      }
    }
  ) {
    id
    createdAt
    owner {
      name
    }
  }
}

6. Next steps

You can now connect to Prisma's GraphQL API, select what you would like to do next:

Examples

Collection of Prisma example projects 💡

You can also check the AirBnB clone example we built as a fully-featured demo app for Prisma.

Architecture

Prisma takes the role of a data access layer in your backend architecture by connecting your API server to your databases. It enables a layered architecture which leads to better separation of concerns and improves maintainability of the entire backend.

Acting as a GraphQL database proxy, Prisma provides a GraphQL-based abstraction for your databases enabling you to read and write data with GraphQL queries and mutations. Using Prisma bindings, you can access Prisma's GraphQL API from your programming language.

Prisma servers run as standalone processes which allows for them to be scaled independently from your API server.

Is Prisma an ORM?

Prisma provides a mapping from your API to your database. In that sense, it solves similar problems as conventional ORMs. The big difference between Prisma and other ORMs is the way how the mapping is implemented.

Prisma takes a radically different approach which avoids the shortcomings and limitations commonly experienced with ORMs. The core idea is that Prisma turns your database into a GraphQL API which is then consumed by your API server (via GraphQL binding). While this makes Prisma particularly well-suited for building GraphQL servers, it can definetely be used in other contexts as well.

Here is how Prisma compares to conventional ORMs:

  • Expressiveness: Full flexibility thanks to Prisma's GraphQL API, including relational filters and nested mutations.
  • Performance: Prisma uses various optimization techniques to ensure top performance in complex scenarios.
  • Architecture: Using Prisma enables a layered and clean architecture, allowing you to focus on your API layer.
  • Type safety: Thanks to GraphQL's strong type system you're getting a strongly typed API layer for free.
  • Realtime: Out-of-the-box support for realtime updates for all events happening in the database.

Database Connectors

Database connectors provide the link between Prisma and the underlying database.

You can connect the following databases to Prisma already:

  • MySQL
  • Postgres

More database connectors will follow.

Upcoming Connectors

If you are interested to participate in the preview for one of the following connectors, please reach out in our Slack.

Further Connectors

We are still collecting use cases and feedback for the API design and feature set of the following connectors:

Join the discussion or contribute to influence which we'll work on next!

GraphQL API

The most important component in Prisma is the GraphQL API:

  • Query, mutate & stream data via a auto-generated GraphQL CRUD API
  • Define your data model and perform migrations using GraphQL SDL

Prisma's auto-generated GraphQL APIs are fully compatible with the OpenCRUD standard.

Try the online demo!

Community

Prisma has a community of thousands of amazing developers and contributors. Welcome, please join us! 👋

Contributing

Contributions are welcome and extremely helpful 🙌 Please refer to the contribution guide for more information.

Releases are separated into two channels - the stable and unstable channel.

  • The stable channel is released every two weeks, incrementing the minor version number. Irregular releases in between minor releases can occur and increment the patch version.

  • The unstable channel is released with every commit to master and therefore gives access to features and bug fixes before the stable release. You can find more information about running the Prisma on the unstable channel here.

Prisma