September 11, 2018

Prisma Client (Preview): Simplified & Type-safe Database Access

The Prisma client is an auto-generated library that can be used as an alternative to Prisma bindings to access data in your applications. It is available in JavaScript, TypeScript, Flow and Go.

Prisma client: The next evolution of Prisma bindings

Prisma turns your database into a GraphQL API. This GraphQL API is usually not consumed directly by frontend applications, but is used as a database abstraction to simplify data access in application servers (similar to an ORM).

When implementing a GraphQL server with Prisma, the resolvers of your GraphQL servers connect to the Prisma API using Prisma bindings and schema delegation.

Schema delegation is an advanced way to implement resolvers by forwarding incoming requests (using the info object) to another GraphQL API.

While schema delegation is a powerful and elegant concept, it is best suited for advanced use cases. Striving to make Prisma more flexible and easier to use, we are introducing a new way to consume Prisma's API in your application: The Prisma client.



More use cases: Build GraphQL servers, REST APIs & more

The new Prisma client serves a similar purpose as Prisma bindings with three major differences:

  • While Prisma bindings are designed for GraphQL servers, Prisma client is more flexible and can be used for more use cases such as REST APIs, CLIs, scripting, etc.
  • Prisma client is an integral part of the Prisma toolchain: It is configured in prisma.yml and generated with the Prisma CLI.
  • Prisma client is available in various languages. Today's preview release makes it available in JavaScript, TypeScript, Flow and Go!

Can I still use Prisma bindings for my GraphQL server?

Prisma bindings remain a powerful way to implement GraphQL resolvers by delegating to the underlying Prisma API. If Prisma bindings work well for your current use case, there is no need to change your implementation to use the new Prisma client.


Generating the Prisma client

Prisma client is a library that connects to your Prisma API. It is auto-generated based on your Prisma datamodel and thus aware of all API operations and data structures.

To generate a Prisma client, you need to do two things:

  1. Specify the new generate property in your prisma.yml, e.g.:

    generate:
      - generator: typescript-client
        output: ./prisma-client/
    
  2. Run the new prisma generate command in the Prisma CLI. It reads information from prisma.yml and your datamodel to generate the Prisma client. Note that this only works with Prisma 1.17-beta or higher.

The code above demonstrates how to generate the client in TypeScript; for JavaScript, Flow and Go you can use the following values for generator: javascript-client, flow-client and go-client.

Using the Prisma client API

The Prisma client API is generated based on your datamodel and exposes CRUD operations for each model.

All following code examples are based on the datamodel below:

type Post {
  id: ID! @unique
  title: String!
  author: User!
}

type User {
  id: ID! @unique
  email: String! @unique
  name: String!
  posts: [Post!]!
}

You can check out the full documentation for the new Prisma client API here.

Importing the Prisma client instance

Once generated, you can import the Prisma client instance into your code:

JavaScript
TypeScript
Go
const { prisma } = require("./prisma-client")

Reading data

While Prisma bindings expose all queries via the query field, queries can be invoked directly on the generated Prisma client:

JavaScript
TypeScript
Go
const allUsers = await prisma.users()

This returns all scalar fields of the returned User objects. Relations can be queried elegantly using method chaining (also referred to as a fluent API):

JavaScript
TypeScript
Go
const postsByUser = await prisma
  .user({ email: "alice@prisma.io" })
  .posts()

Note that the snippet above still results in a single request to the Prisma API which is then resolved against the database by Prisma's powerful query engine.

It is also still possible to use GraphQL to query nested data or use schema delegation for advanced use cases with the new Prisma client API.

See more examples in the documentation.

Writing data

Just like queries, mutations are also exposed on the top-level on your Prisma client:

JavaScript
TypeScript
Go
const newUser = await prisma.createUser({
  name: "Alice",
  email: "alice@prisma.io"
})

You can also perform several write operations in a single transaction:

JavaScript
TypeScript
Go
const newUserWithPosts = await prisma.createUser({
  name: "Bob",
  email: "bob@prisma.io",
  posts: {
    create: [{
      title: "Hello World"
    }, {
      title: "I ❤️ Prisma"
    }],
  }
})

See more examples in the documentation.

No boilerplate: Type-safety through code generation

One core benefit of the Prisma client is type-safety. Type-safety fosters productivity, better maintainability, easier refactoring and makes for a great developer experience.

Type-safe data access requires a lot of manual work, writing boilerplate code and redundant type definitions. The Prisma client leverages code generation in order to provide custom typings for data models and queries.


Try out Prisma client

To learn more about the Prisma client, check out the new examples repository or follow the "Get Started" tutorial. Please let us know what you think on Slack 🙌



Get started

Comments

Comments

Don’t miss the next post!