Developer Preview: Graphcool 1.0 Beta


#1

Update

The developer preview of Graphcool 1.0 has been released as a separated component called Prisma.
Please read Graphcool Framework and Prisma for more information.


Introduction

After open-sourcing the Graphcool Framework, we have been working hard to improve the core features of Graphcool.

Today, we are excited to finally share a first preview of what the future of Graphcool looks like :tada:

Getting started

You can use the Node.js boilerplates or TypeScript boilerplates to get started with the beta.
For more background information, the announcement blog post describes the overall changes in 1.0 on a high level.

You can also checkout the documentation for Prisma or the following video to see a demo:

Common Questions

Developer Preview

What happens to my legacy or framework projects?

Existing legacy and framework projects will continue to work as long as you’d like.
Services created with Prisma will be deployed to a separate cluster.

We will soon release more information on how you can easily switch from legacy or framework projects to Prisma. It will be easy to import and export data between either projects, which will simplify this experience a lot :slightly_smiling_face:

What is the best way to upgrade to Prisma?

Currently, it is not recommended to upgrade your production project to the developer preview of Prisma. We will provide an upgrading guide when releasing Prisma officially. Subscribe to this PR to stay informed about our progress:

Can I deploy projects to a shared cluster during the beta?

Yes! :slightly_smiling_face:

How can I follow along with the process during the beta?

The best way to follow along the progress during the beta regarding features and examples is to subscribe to the following PR:

We’ll keep it posted with updates for new features and examples.

Prisma

How stable will Prisma be? It has been the core focus for the PRisma release to have a stable foundation for many new features without the need to introduce breaking changes.

There are still a couple of changes coming up until it’s out of beta, but most of the lined up changes are additive. See here for the roadmap: https://github.com/graphcool/framework/pull/1318

How is the SDL going to change in Prisma?

The Node boilerplates showcase the new SDL syntax. This is an example datamodel with the new SDL syntax:

type Post {
  id: ID! @unique
  createdAt: DateTime!
  updatedAt: DateTime!
  isPublished: Boolean! @default(value: false)
  title: String!
  text: String!
  author: User! @relation(name: "UserPosts")
}

type User {
  id: ID! @unique
  email: String! @unique
  password: String!
  name: String!
  posts: [Post!]! @relation(name: "UserPosts")

Note:

  • @model is not needed anymore
  • @isUnique has been renamed to @unique
  • @defaultValue has been renamed to @default
  • @relation is optional in some cases

More information can be found here and here.

How does authorization work in Prisma?

Permission queries provide a declarative approach to express authorization rules. We’re aiming to provide a similar experience with graphcool-binding and we’re currently discussing a concrete Permission API. Please join the discussion with your thoughts :slightly_smiling_face:

Going forward, we will provide examples that showcase how you can implement different authorization approaches, you can subscribe to this PR to stay notified about updates here.

How can I implement authentication in Prisma?
  • For sign up, you can create a new node, for example of type User
  • For login, you can return a signed JWT, that contains relevant information about the user, like its id

Check one of the the boilerplates her to see how this looks like in action!

How can I implement X in version Prisma? Here's a list of topics that will be covered in examples to be released soon:
Examples
  • Authentication
  • Authorization
  • Resolvers
  • File Handling
  • REST API wrapper
  • Serverless integration
  • Subscriptions
Guides
  • Data import/export
  • Upgrade projects to Prisma

If you would like to see an example about a different topic, please let us know in the comments below.

Do I now have to write database resolvers myself? No! Automatically mapping the API to the Database is one of the core features of Graphcool.

Using graphcool-binding, you can then implement your application GraphQL API which is exposed to GraphQL clients.

Check out this example to see how this looks like in practice.

Technical Questions

Can I work with old projects and new projects at the same time?

Yes, but you need to make sure to install the correct CLI version.

Get the Prisma CLI

npm install -g prisma

Get the Framework CLI

npm install -g graphcool-framework
Do I have to host the GraphQL server myself?

The database server can be deployed to the Cloud. We recommend hosting the application server with services like Zeit’s now.

Do I have to implement the GraphQL server in Node?

No! Most of our examples use Node, because its available GraphQL tooling is the most mature, and Node is a very common server technology. However, you can choose any platform as your GraphQL server technology that you want.

I'm getting a 'Schema could not be fetched.' error after deploying, what gives? Access to the Graphcool API is secured by a secret. This also applies to the introspection query. Using the latest version of GraphQL Playground, the `Authorization` header should automatically be setup with a proper JWT signing the secret. If that's not the case, you can follow these steps to access your API:
  • Visit http://jwtbuilder.jamiekurtz.com/
  • Replace the Key at the bottom of the page with your database secret
  • Click Create signed JWT and copy the obtained token
  • Now, to access the schema, use the Authorization: Bearer <token> header, or in the GraphQL Playground set it as JSON:
{
  "Authorization": "Bearer <token>"
}

Feedback

One key aspect of Graphcool has always been the feedback from customers and the community :green_heart:
I am super excited about Prisma, and would love your participation along the way.

Let me know if you have any kind of questions and provide your feedback in the comments below.

Thanks :pray:
– Nilan


Can I create my own custom authentication?
Viewing console.log for Graphcool framework
Bash: graphcool: command not found
Trouble installing graphcool on mac
How make a very, very simple mutation, from an authorized user?
Unable to deploy How To GraphQL
#2

Thanks for the wonderful updates. I am a bit ‘out of date’ and still use graphcool cli v0.8.5. I can see the project structure has changed a lot and there is a yoga server sitting in between client and Graphcool database. I am very eager to try the new 1.0, but I do have a live system that I need to keep running safely. Is it possible for your team to produce a guide of upgrading? I would really appreciate it :muscle:


#8

Currently, I love Graphcool because of the whole idea of not needing to host a backend myself, instead, I just need to host frontend JS files. As of right now I am using the Graphcool Framework and it is great because I have version control and full access to the files while at the same time I am not actually having to host any of them. My question is, with the introduction of the new 1.0, will I be able to keep things the way they are currently? For instance, will I need to host a database or server myself? Or, will I be able to continue to use the Graphcool Cloud and have the server and database hosted for me still? Sorry if my question does not make a ton of sense, but I am just a little bit confused on what could possibly change for me from the way things are right now with the current version of the Graphcool Framework. Thank you, Michael.


#9

I can’t figure how to use the updated CLI. For example, I spun up the basic project and tried to add a User type. graphcool local up and graphcool deploy did the correct codegen on database/schema.graphql, but playground queries to the User type end up in giant data variable, where variable, etc errors. It looks like the database isn’t migrating.

e.g. resolver

users(parent, args, ctx, info) {
      return ctx.db.query.users() // or ...users(info) or ... users({}, info)
    }

and schema.graphql

type Query {
  feed: [Post!]!
  users: [User!]!
}

and query

{
  users {
    name
  }
}

returns

{
  "data": {
    "users": null
  },
  "errors": [
    {
      "message": "Variable '$_where' cannot be non input type 'UserFilter'. (line 1, column 17):
query ($_where: UserFilter, $_orderBy: UserOrderBy, $_skip: Int, $_after: String, $_before: String, $_first: Int, $_last: Int) {
               ^\nUnknown type 'UserFilter'. Did you mean 'PostFilter'? 
...

Thanks for the help!


#10

Thanks for your question @yunjia.li :+1:

Currently, it is not recommended to upgrade your production project to the developer preview of Graphcool 1.0.

We will provide an upgrading guide when releasing Graphcool 1.0 officially. Subscribe to this PR to stay informed about our progress:

I added your question at “What is the best way to upgrade to Graphcool 1.0?” in my original post :slightly_smiling_face:


#11

Your question makes a lot of sense, thanks Michael!

First of all, I encourage you to read the announcement blog post of the developer preview, to get a better understanding of the features coming in Graphcool 1.0. Make sure to check out the extensive example as well, that’s the best way of getting a feel for the developer experience :slight_smile:


In Graphcool 1.0, both the database/database server and the application server can be deployed to the Cloud.

We’re actively building tools to provide a great development experience while developing your GraphQL app:

We’re also contributing to grahql-tools and are super excited about the recent advancements in the area of schema stitching.

As for hosting the application server, you can look into using services like Zeit’s now, while the database server is currently deployed to AWS. We’ll release more resources about deployment soon, so stay tuned!

Let me know if you have any other questions! :raised_hands:
Best
– Nilan


#12

Hey @LawJolla, I cannot reproduce your issue. Here’s what I did:

  • graphql create new-project

  • select Minimal example

  • add User type to database/datamodel.graphql like this:

    type User {
      id: ID! @unique
      name: String
    }
    
  • add a users field to the Query object in src/index.js:

    Query: {
      feed(parent, args, ctx, info) {
        return ctx.db.query.posts({ where: { isPublished: true } }, info)
      },
      users(parent, args, ctx, info) {
        return ctx.db.query.users()
      },
    },
    
  • graphcool deploy

  • select local cluster

  • yarn start

  • open http://localhost:4000

  • run this query:

    query a {
      users {
        id
        name
      }
    }
    
  • The response:

    {
      "data": {
        "users": [
          {
            "id": "cjb7y4ud1003e0176br09z4aa",
            "name": "Nilan"
          }
        ]
      }
    }
    

    (I previously added that user).

Could you please describe a reproduction directly in the repository for the minimal template? :slight_smile:
Thanks a lot!


#13

With new framework its needed to write all application resolvers? Or will be there any possibility to have it automatically generated?


#14

Hello, thank you for your response! So just to clarify, I will be able to have the database and application server hosted through the Graphcool Cloud, but could also host them myself if I needed to? Thank You.


#15

Hey Michael, currently the application server is deployed outside of the Graphcool Cloud, as I mentioned here:


#16

Hey @Huvik, thanks for your question :slight_smile:

All resolvers in the application server are under your control. Using graphcool-binding adding a new resolver is as easy as adding

  feed(parent, args, ctx, info) {
    return ctx.db.query.posts(info)
  },

for example.


#17

I just added a new question to the original post: “How does authorization work in 1.0?”


#18

Thanks @nilan! I went over this over and over but couldn’t make it work.

I scrapped the demo, created a new one, and had zero issues. I think there was some corruption on the build.


#19

I just added a new question to the original post: “How can I implement authentication in 1.0?”


#20

How is whole SDL going to change from previous version?


#21

Great question, @Huvik! :raised_hands:

I just added a new question “How is the SDL going to change in 1.0?” to my original post :slight_smile:


#22

Is there support for Server Side Subscriptions in 1.0?


#23

Can we host this in a serverless fashion on AWS Lambda or Google Cloud Functions? Zeit’s now is public (code) for the free plan and their paid plan might not make sense for everyone.

Does Graphcool have any plan of providing a hosted environment for GraphQL server?


#24

This looks really solid to me, thanks for all the hard work Graphcool team. To increase my understanding, let me summarize my experience with Graphcool 1.0 (so far), you can maybe answer each of my points and correct me where I am wrong and add where I am partially correct :slightly_smiling_face:

  1. Graphcool cluster is more like a DAO (data-access-object) layer now! and provides us with DB object using context that has common CRUD functions (can we add functions to this DB object from context?) on top of it.

  2. API moves to GraphQL server, so, the developer gets total control of how he wants the API to be like, nothing less, nothing more. This will also help in migration because we will be able to match the existing deployed API for production apps.

  3. Auth/permissions also moves to GraphQL server, simplest implementation would involve creating a User type and API by using the User type DAO, much like posts but we have more control now on authentication/authorization logic.


#25

Thanks a lot for your questions, @divyenduz!

  • Can we host this in a serverless fashion on AWS Lambda or Google Cloud Functions?

    Yes, but this will not work if you need subscriptions (due to the websocket connection). We are exploring how we can make the hosting as easy as possible :slight_smile:

  • Graphcool cluster is more like a DAO layer now

    Yes, Graphcool DB turns your DB into a GraphQL API. You can use the Graphcool binding in your code to access the resulting GraphQL API. Currently, it’s not possible to add functions to this binding yourself, but that sounds like a great feature request! Would be great if you could make a suggestion on how this could look like here.

  • The developer gets total control of how he wants the API to be like

    Yes, and this is simplified with tools for what is commonly referred to as ‘schema stitching’. Check the boilerplate examples to see how this looks like in practice. Note that with this approach, your resulting application GraphQL API can be designed to be specific to your app, compared to the general purpose API that Graphcool exposes automatically. I assume that it’s beneficial for most applications to transition over to a specific API.

  • Auth/permissions also moves to GraphQL server

    Yes! We’re currently preparing examples that showcase how you can implement this for different scenarios. Furthermore, here’s an interesting discussion about how defining permissions could be simplified by the Graphcool binding.

Thanks so much for your great questions & input, hope this clears things up for you! :raised_hands: