Deploy a Netlify App Built on CockroachDB

On this page Carat arrow pointing down
Warning:
CockroachDB v21.2 is no longer supported. For more details, see the Release Support Policy.

This tutorial shows you how to deploy a Netlify web application that communicates with a CockroachDB Serverless cluster.

The sample app used in this tutorial simulates a gaming leaderboard. The Netlify functions used for the app are written in TypeScript. The functions use Prisma to connect to CockroachDB. The app's frontend, also written in TypeScript, uses React, bootstrapped with Create React App.

The source code for the completed app is available on GitHub at https://github.com/cockroachdb/cockroachdb-typescript.

Prerequisites

Before starting the tutorial, do the following:

  1. Create a CockroachDB Cloud account.

  2. Create a Starter Netlify account. You can do this with your GitHub login credentials.

Step 1. Create a CockroachDB Serverless cluster

Note:

Organizations without billing information on file can only create one CockroachDB Serverless cluster.

  1. If you haven't already, sign up for a CockroachDB Cloud account.
  2. Log in to your CockroachDB Cloud account.
  3. On the Clusters page, click Create Cluster.
  4. On the Select a plan page, select Serverless.
  5. On the Cloud & Regions page, select a cloud provider (GCP or AWS) in the Cloud provider section.
  6. In the Regions section, select a region for the cluster. Refer to CockroachDB Cloud Regions for the regions where CockroachDB Serverless clusters can be deployed. To create a multi-region cluster, click Add region and select additional regions. A cluster can have at most six regions.
  7. Click Next: Capacity.
  8. On the Capacity page, select Start for free. Click Next: Finalize.
  9. On the Finalize page, click Create cluster.

    Your cluster will be created in a few seconds and the Create SQL user dialog will display.

After the cluster is created, the Connection info window appears. Click the Connection string tab and copy the connection string to a secure location. You will use this connection string to connect to CockroachDB later in the tutorial.

Note:

The connection string is pre-populated with your username, cluster name, and other details, including your password. Your password, in particular, will be provided only once. Save it in a secure place (we recommend a password manager) to connect to your cluster in the future. If you forget your password, you can reset it by going to the SQL Users page for the cluster, found at https://cockroachlabs.cloud/cluster/<CLUSTER ID>/users.

Step 2. Get the code

  1. Clone the code's GitHub repo:

    icon/buttons/copy
    $ git clone git@github.com:cockroachdb/cockroachdb-typescript.git
    

    The project has the following directory structure:

    ├── LICENSE.md
    ├── README.md
    ├── netlify
    │   └── functions
    │       ├── addScore.ts
    │       ├── getPlayers.ts
    │       └── getScores.ts
    ├── package-lock.json
    ├── package.json
    ├── prisma
    │   ├── schema.prisma
    │   └── seed.ts
    ├── public
    ├── src
    └── tsconfig.json
    

    In this tutorial, we focus on the files in the netlify and prisma directories.

  2. At the top of the repo directory, fork the repo:

    icon/buttons/copy
    $ gh repo fork --remote
    

    To deploy your code to Netlify, you need to have your own repo or your own fork of the existing repo.

Step 3. Initialize the database

  1. In the .env file in your project, set the DATABASE_URL environment variable to the connection string you obtained earlier from the CockroachDB Cloud Console:

    icon/buttons/copy
    DATABASE_URL=<connection-string>
    

    Prisma loads the variables defined in .env to the project environment.

  2. Install Prisma:

    icon/buttons/copy
    npm install prisma --save-dev
    
  3. Run Prisma Migrate to initialize the database with the schema defined in prisma/prisma.schema.

    icon/buttons/copy
    $ npx prisma migrate dev --name init
    

    You should see the following output:

    Your database is now in sync with your schema.
    ✔ Generated Prisma Client (3.11.0 | library) to ./node_modules/@prisma/client in 87ms
    
    Running seed command `ts-node --compiler-options {"module":"CommonJS"} prisma/seed.ts` ...
    {
      test_player_1: { id: 1n, name: 'Test Player 1', email: 'test_player_1@example.com' },
      test_player_2: { id: 2n, name: 'Test Player 2', email: 'test_player_2@example.com' },
      test_player_3: { id: 3n, name: 'Test Player 3', email: 'test_player_3@example.com' }
    }
    
    🌱  The seed command has been executed.
    

    This command initializes Prisma Client to communicate with your CockroachDB cluster, based on the configuration in the prisma/schema.prisma file. The command also seeds your database with some sample data, using the script defined in prisma/seed.ts.

Step 4. Deploy the application

You can deploy web applications directly from GitHub to Netlify. In this tutorial, we use the Netlify CLI to deploy the app.

  1. Install the netlify CLI:

    icon/buttons/copy
    $ npm install netlify-cli -g
    
  2. Sign into your Netlify account:

    icon/buttons/copy
    $ netlify login
    
  3. Run the app server locally to preview your site:

    icon/buttons/copy
    $ netlify dev
    

    If the local deployment succeeds, you should see the following message in your terminal:

    ┌─────────────────────────────────────────────────┐
    │                                                 │
    │   ◈ Server now ready on http://localhost:8888   │
    │                                                 │
    └─────────────────────────────────────────────────┘
    

    For a preview of the site, visit http://localhost:8888.

    Interacting with the site triggers the Netlify functions defined in the netlify/functions directory. These functions use Prisma Client to run SELECT and INSERT queries against the database:

    • getScores.ts reads all rows from the player_scores table and returns values in the id, name, and score columns.
    • getPlayers.ts reads and returns all rows from the players table.
    • addScore.ts writes new scores to the player_scores table.
  4. Deploy your app with the Netlify CLI:

    icon/buttons/copy
    $ netlify deploy
    

    Choose to create a new site, and then select the default options for each of the subsequent prompts. You will be required to authorize Netlify with GitHub.

    After the app is deployed, you should see the following message:

    ✔ Deploy is live!
    
  5. Navigate to the admin URL for your site:

    icon/buttons/copy
    $ netlify open
    

    From the Site overview page, you can manage your site. The Site overview page also provides you with a public URL for your site.

See also

You might also be interested in the following pages:


Yes No
On this page

Yes No