Looking for the Prisma documentation? You can find it here

Migration Guide for Legacy Console Projects

Last updated a day ago Edit this page

#Terminology

When creating a backend with Graphcool, we used to refer to it as a project. In the future we will refer to this as a service. During the transition we will use legacy Console project to refer to old projects and Graphcool Service to refer to services created using the new CLI that was introduced with the Framework Preview.

If you have recently started using Graphcool and are unsure what version you are using, this is how you can find out:

  • Legacy Console Project: Projects created with any CLI version lower than 0.4 or in the Console. Legacy Console projects are not using the graphcool.yml service definition file, but simply pull the current data model from the old project configuration file project.graphcool. If you go to the console you will be able to edit your schema, functions etc.
  • Graphcool Service: Graphcool services that were created with any CLI version greater or equal to 0.4. If you go to the console you will not be able to edit your schema, functions etc.

#Can I continue to use my legacy console project?

Yes!

While most new features added to the Graphcool Framework will require you to upgrade to a Graphcool service, you can continue to use your legacy Console project without change.

Legacy Console projects can only use CLI versions lower than 0.4 and are primarily managed through the Console. Particularly, managing functions and permissions can only be done in the Console.

Managing the GraphQL type definitions can still be done both in the Console (in the Schema Editor) and the old CLI (using graphcool pull and graphcool push).

#Upgrading a legacy Console project to a Graphcool service

#"Dry-run" migration to gain familiarity with new CLI

Before upgrading your legacy Console project to a Graphcool service, we recommend that you're doing a "dry-run" of the upgrade process to get familiar with the new workflows.

You can find more info in this GitHub issue.

1. Obtain your service definition

The first thing you need to do is get access to the service definition of your legacy project. This can be done with the new Graphcool CLI and the following command:

graphcool init --copy <legacyProjectId>

This will download all the files that represent the functionality of your Graphcool project into the current directory. You can also download all files into a new directory, e.g. called service, by adding the directory name as an argument to the CLI command:

graphcool init service --copy <legacyProjectId>

2. Install node dependencies for functions (if necessary)

If your legacy Console project makes use of any serverless functions that you've previously configured through the Graphcool Console, the service definition created in the previous step will now contain the source files for these functions.

When deploying functions using the new CLI, you explicitly need to add the node dependencies to your service by adding them to your package.json file (using npm install --save <package> or yarn add <package>). For example, if a function in your projects uses the graphcool-lib package, you need to add it to your service's package.json like so:

npm install --save graphcool-lib # or yarn add graphcool-lib

3. Deploy and test

You can now deploy your service with the following command:

graphcool deploy

You can either deploy to a Shared Cluster or locally with Docker. Once you deployed the service, you can add some test data using a Playground.

#Actual upgrade process

In most cases upgrading a legacy Console project to a Graphcool service is a simple process.

It is important to understand that once a project is upgraded to a Graphcool service, it can not be converted back to a legacy Console project again.

To upgrade a legacy Console project to a Graphcool service, you need to navigate to the Project Settings in the Console, select the General-tab and click the Upgrade Project-button:

Upgrading a project is a one-way migration. If you have any concerns about the process, please ask a question in the Forum.

After the project was upgraded, you need to download the project configuration of the project so you can use it with the new CLI:

#Deprecated features

A few features are being deprecated as part of the Framework release. If your legacy Console project is currently using any of these features you will have to replace the functionality before you can upgrade. The following features have been deprecated:

  • Integrations: If you are currently using the Algolia integration or any of the Auth Providers that can be configured in the console, you should transition to one of the many templates available on Github.
  • Request Pipeline functions with a PRE_WRITE step: Depending on your use case, you can either move the code to TRANSFORM_ARGUMENT or to a Server-side Subscription.

Was this page helpful?