DEV Community: Daniel Norman

Deploying Prisma to Azure Functions with Azure SQL

Daniel Norman — Mon, 22 Mar 2021 12:24:28 +0000

Overview

In this guide, you will set up and deploy a Prisma based Node.js REST API to Azure Functions together with Azure SQL as the database. The application will expose a REST API and use Prisma Client to handle fetching, creating, and deleting records from a database.

Azure Functions is a serverless deployment platform that allows you to deploy code without having to maintain infrastructure. Azure SQL Database is a relational database service built for the cloud with automatic scaling.

In this guide, you will create the necessary resources in Azure, create the database schema using Prisma Migrate and deploy a Node.js REST API with resource endpoints that use Prisma Client to handle database operations against the Azure SQL database.

This guide's focus is showing how Prisma can be used in the Azure cloud focusing on Azure Functions and Azure SQL. The starting point is the Prisma Azure Functions example – a REST API for a simple blog with two models: User and Post (1:n). The example contains REST endpoints preconfigured as serverless functions.

Note that Azure SQL support in Prisma is in Preview.

With Azure Functions, the fundamental building block is a Function App. A function app provides an execution context in Azure in which your functions run. It is comprised of one or more individual functions that are managed, deployed, and scaled together. That way, you can organize and collectively manage multiple functions as a single logical unit.

Throughout the guide, you'll find various checkpoints that enable you to validate whether you performed the steps correctly.

Prerequisites

Azure account.
Git installed
Azure CLI installed.
Node.js installed.

Prisma workflow

At the core of Prisma is the Prisma schema – a declarative configuration where you define your data model and other Prisma-related configuration. The Prisma schema is also a single source of truth for both Prisma Client and Prisma Migrate.

In this guide, you will use Prisma Migrate to create the database schema. Prisma Migrate is based on the Prisma schema and works by generating .sql migration files that are executed against the database.

Migrate comes with two primary workflows:

Creating migrations and applying during local development with prisma migrate dev
Applying generated migration to production with prisma migrate deploy

For brevity, the guide does not cover how migrations are created with prisma migrate dev. Rather, it focuses on the production workflow with prisma migrate deploy and uses the Prisma schema and SQL migration that are included in the example code.

To learn more about how migrations are created with Prisma Migrate, check out the start from scratch guide

Required Azure resources

Resource group
Azure SQL Database server
Database
Firewall rule
Storage account
Function App

1. Download the example and install dependencies

Open your terminal and navigate to a location of your choice.

Create the directory for the application code and download the example code:

mkdir prisma-azure
cd prisma-azure
curl https://codeload.github.com/prisma/prisma-examples/tar.gz/latest | tar -xz --strip=3 prisma-examples-latest/deployment-platforms/azure-functions/

Checkpoint: Run the following command to list the contents of the folder:

ls -1

You should see the following files

CreatePost/
CreateUser/
DeletePost/
FilterPosts/
GetFeed/
GetPost/
PublishPost/
host.json
lib/
node_modules/
package.json
prisma/
proxies.json

Install the dependencies:

npm install

2. Sign in to Azure using the Azure CLI

Begin by signing in using the following command in your terminal:

az login

3. Create the Resource Group on Azure

In Azure, a resource group is a way to group together different cloud resources. Whenever you create a resource, e.g., an Azure Function, you need to assign it a resource group.

Since the REST API will use both Azure Functions and an Azure SQL database, you will first create the resource group with the following command:

az group create --location germanywestcentral --name prisma-azure-example

Note: The command above creates the resource group in the germanywestcentral region. You should create the resource group in the region closest to your users. For the full list of Azure regions, run the az account list-locations command.

Checkpoint: The command should output information about the created resource group:

{
  "id": "/subscriptions/SUBSCRIPTION_ID/resourceGroups/prisma-azure-example",
  "location": "germanywestcentral",
  "managedBy": null,
  "name": "prisma-azure-example",
  "properties": {
    "provisioningState": "Succeeded"
  },
  "tags": null,
  "type": "Microsoft.Resources/resourceGroups"
}

4. Create the Azure SQL database server

To create the Azure SQL database server, copy the command below into your terminal:

az sql server create -l germanywestcentral -g prisma-azure-example --name UNIQUE_DB_SERVER_NAME --admin-user prisma --admin-password CHOOSE_A_PASSWORD --enable-public-network true

Before running the command, replace a unique name for the database in place of UNIQUE_DB_SERVER_NAME, set a password in place of CHOOSE_A_PASSWORD, and note it down.

The command does the following:

Creates the database server in the germanywestcentral region.
Associates it with the prisma-azure-example resource group created in the previous step.
Sets a unique name for the Azure SQL server with UNIQUE_DB_SERVER_NAME.
Sets the admin user to prisma.
Sets the admin password.
Enables public network access so you can create the database schema from your machine.

In the next step, you will create the database that Prisma will use in the REST API.

5. Create the database

In this step, you will create a database in the server you created in the previous step.

Run the following command in the terminal, replace UNIQUE_DB_SERVER_NAME with the database name you chose in the previous step:

az sql db create --resource-group prisma-azure-example --server UNIQUE_DB_SERVER_NAME --name prisma-azure-example --service-objective Basic

Here's a breakdown of the command's parameters:

--resource-group adds the database to the resource group created in step 3
--server sets the Azure SQL database server to create it in
--name sets the name of the database
--service-objective sets the database's service tier that determines the cost.

6. Create a firewall rule to allow local access to the database

In this step, you will add two firewall rules:

Allow remote access from your local computer's public IP to the Azure SQL database. This is necessary so you can create the database schema and use the database for testing locally.
Allow access to the Azure SQL database from Azure Functions

Allow access from your local computer

Begin by determining your public IP with the following command:

curl ifconfig.me

Copy the IP from the output and run the following command, replacing YOUR_PUBLIC_IP with the IP address and UNIQUE_DB_SERVER_NAME with the name from step 4:

az sql server firewall-rule create --resource-group prisma-azure-example --server UNIQUE_DB_SERVER_NAME --name allow-local-acccess --start-ip-address YOUR_PUBLIC_IP --end-ip-address YOUR_PUBLIC_IP

Checkpoint: After creating the firewall rule, the command should output the following:

{
  "endIpAddress": "YOUR_PUBLIC_IP",
  "id": "/subscriptions/YOUR_SUBSCRIPTION_ID/resourceGroups/prisma-azure-example/providers/Microsoft.Sql/servers/prisma-db/firewallRules/allow-local-acccess",
  "kind": "v12.0",
  "location": "Germany West Central",
  "name": "allow-local-acccess",
  "resourceGroup": "prisma-azure-example",
  "startIpAddress": "YOUR_PUBLIC_IP",
  "type": "Microsoft.Sql/servers/firewallRules"
}

Allow access from Azure Functions

To allow applications hosted inside Azure to connect to your SQL server, Azure connections must be enabled. To enable Azure connections, there must be a firewall rule with starting and ending IP addresses set to 0.0.0.0.

Create the rule with the following command:

az sql server firewall-rule create --resource-group prisma-azure-example --server UNIQUE_DB_SERVER_NAME --name allow-function-acccess --start-ip-address 0.0.0.0 --end-ip-address 0.0.0.0

7. Create a storage account

In this step, you will create a storage account used to maintain state and other information about your functions.

Run the following command to create the storage account, replacing UNIQUE_STORAGE_ACCOUNT_NAME with a name for the stroage account:

az storage account create --name UNIQUE_STORAGE_ACCOUNT_NAME --location germanywestcentral --resource-group prisma-azure-example --sku Standard_LRS

Checkpoint: If the command succeeds, it will output a large json object. Verify that provisioningState is Succeeded:

{
  "id": "/subscriptions/YOUR_SUBSCRIPTION_ID/resourceGroups/prisma-azure-example/providers/Microsoft.Storage/storageAccounts/UNIQUE_STORAGE_ACCOUNT_NAME",
  "provisioningState": "Succeeded",
  "resourceGroup": "prisma-azure-example",
  "type": "Microsoft.Storage/storageAccounts"
}

8. Create the function app

In this step, you will create the function app, which provides the environment for executing your function code. A function app maps to your local function project and lets you group functions as a logical unit for easier management, deployment, and sharing of resources.

Copy the following command and replace FUNCTION_APP_NAME with a unique name for your function app, and STORAGE_ACCOUNT_NAME with the name you chose in the previous step:

az functionapp create --resource-group prisma-azure-example --consumption-plan-location germanywestcentral --runtime node --runtime-version 14 --functions-version 3 --name FUNCTION_APP_NAME --storage-account STORAGE_ACCOUNT_NAME --os-type Linux

Note: The Function App name must be globally unique as it will determine the subdomain of the deployed function.

Checkpoint: If the command succeeds, you will see a large JSON object in the terminal. Verify that that the state key in the object is set to Running.

9. Set the DATABASE_URL environment variable locally

In this step, you will define the DATABASE_URL environment variable locally to create the database schema and test the functions locally.

To construct the connection string, copy the following connection string template:

sqlserver://DB_SERVER_NAME.database.windows.net:1433;database=DB_NAME;user=DB_ADMIN_USER@DB_SERVER_NAME;password={DB_ADMIN_PASSWORD};encrypt=true;trustServerCertificate=false;hostNameInCertificate=*.database.windows.net;loginTimeout=30

Replace the following parts:

DB_SERVER_NAME with the database server name defined in step 4
DB_NAME with the database name defined in step 5
DB_ADMIN_USER with the database admin user set in step 4 to prisma
DB_ADMIN_PASSWORD with the database admin password set in step 4

After setting all the values, set it as a local environment variable:

export DATABASE_URL="sqlserver://DB_SERVER_NAME.database.windows.net:1433;database=DB_NAME;user=DB_ADMIN_USER@DB_SERVER_NAME;password={DB_ADMIN_PASSWORD};encrypt=true;trustServerCertificate=false;hostNameInCertificate=*.database.windows.net;loginTimeout=30"

10. Create the Azure Functions local configuration

In this step, you will create the local configuration file for Azure Functions. The file is used to define local configuration such as environment variables for the functions and the runtime – in this case Node.js.

Create a file named local.settings.json in the root of the project with the following command:

touch local.settings.json

And add the following contents to it:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "",
    "FUNCTIONS_WORKER_RUNTIME": "node"
  }
}

11. Create the database schema

With the DATABASE_URL environment variable set, you will create the database schema using the prisma migrate deploy command.

Note: The prisma migrate deploy command will run migration files from the prisma/migrations folder. The initial migration is already included in the example. To learn more about how to create migrations, check out the Prisma Migrate docs.

Run the following command to create the database schema:

npx prisma migrate deploy

Checkpoint: The prisma migrate deploy should show the following:

1 migration found in prisma/migrations

The following migration have been applied:

migrations/
  └─ 20210322111219_init/
    └─ migration.sql

All migrations have been successfully applied.

12. Expose the DATABASE_URL environment variable to the functions

In this step, you will expose the DATABASE_URL environment variable to the functions so that Prisma can connect to the database. In Azure Functions, environment variables are set using app settings.

Run the following command, after replacing FUNCTION_APP_NAME_FROM_STEP_8 with the name of the Function App created in step 8:

az functionapp config appsettings set --name FUNCTION_APP_NAME_FROM_STEP_8 --resource-group prisma-azure-example --settings DATABASE_URL=$DATABASE_URL

The command will set the DATABASE_URL app setting using the locally defined DATABASE_URL environment variable set in step 9.

Note: By default, app settings are not encrypted. Since the DATABASE_URL contains sensitive information, it can be stored more securely using Azure's Key Vault

Congratulations! You have created all the necessary resources and configuration, which means your API is ready to be deployed.

13. Deploy the functions

In this step, you will generate Prisma Client and deploy the functions.

From the project folder, run the following command:

npx prisma generate

The command will generate Prisma Client into the node_modules folder.

To deploy the functions, run the following command:

npx func azure functionapp publish FUNCTION_APP_NAME

Checkpoint: If the functions have been successfully deployed you should see the following output:

Getting site publishing info...
Uploading package...
Uploading 67.24 MB [##############################################################################]
Upload completed successfully.
Deployment completed successfully.
Syncing triggers...
Functions in FUNCTION_APP_NAME:
    CreatePost - [httpTrigger]
        Invoke url: https://FUNCTION_APP_NAME.azurewebsites.net/api/post
    CreateUser - [httpTrigger]
        Invoke url: https://FUNCTION_APP_NAME.azurewebsites.net/api/user
    DeletePost - [httpTrigger]
        Invoke url: https://FUNCTION_APP_NAME.azurewebsites.net/api/post/{postid}
    FilterPosts - [httpTrigger]
        Invoke url: https://FUNCTION_APP_NAME.azurewebsites.net/api/filterposts
    GetFeed - [httpTrigger]
        Invoke url: https://FUNCTION_APP_NAME.azurewebsites.net/api/feed
    GetPost - [httpTrigger]
        Invoke url: https://FUNCTION_APP_NAME.azurewebsites.net/api/post/{postid}
    PublishPost - [httpTrigger]
        Invoke url: https://FUNCTION_APP_NAME.azurewebsites.net/api/publish/{postid}

Congratulations 🎊! If you've made it this far, you've successfully deployed a Prisma based REST API to Azure Functions which uses Azure SQL as the database.

In the next step, you'll test the functions and take a closer look at how the functions are implemented.

14. Test the deployed functions

In this step, you will test the API's different endpoints using the URLs from the previous step.

Begin by making a POST HTTP request to the CreateUser endpoint with curl:

curl --request POST --data '{"email":"alice@prisma.io","name":"Alice"}' https://FUNCTION_APP_NAME.azurewebsites.net/api/user

Note: Replace the FUNCTION_APP_NAME in the URL with the app name you chose in step 8.

If the request succeeds, you should see the created user object returned:

{
  "createdAt": "2021-03-02T14:48:15.746Z",
  "email": "alice@prisma.io",
  "id": 1,
  "name": "Alice"
}

The files associated with the function can be found in the CreateUser folder, which contains two files:

function.json: Function configuration, e.g. HTTP method, path, and return value
index.js: The function handler where Prisma Client is used to create the user in the Azure SQL database

Now, try creating a post associated with the user you just created with the following comand:

curl --request POST --data '{"title":"Prisma with Azure","content":"","authorEmail":"alice@prisma.io"}' https://FUNCTION_APP_NAME.azurewebsites.net/api/post

If the request succeeds, you should see the created post object returned:

{
  "id": 1,
  "createdAt": "2021-03-02T17:09:53.160Z",
  "updatedAt": "2021-03-02T17:09:53.161Z",
  "title": "Prisma with Azure",
  "content": "",
  "published": false,
  "authorId": 1
}

To update the published field of the post, make the following request:

curl --request PUT https://FUNCTION_APP_NAME.azurewebsites.net/api/publish/1

If the request succeeds, you should see the updated post object:

{
  "authorId": 1,
  "content": "",
  "createdAt": "2021-03-02T17:09:53.160Z",
  "id": 1,
  "published": true,
  "title": "Prisma with Azure",
  "updatedAt": "2021-03-03T10:07:11.047Z"
}

Finally, to test the feed endpoint, make the following request:

curl https://FUNCTION_APP_NAME.azurewebsites.net/api/feed

If the request succeeds, you should see the post you created and the related author:

[
  {
    "author": {
      "createdAt": "2021-03-02T14:48:15.746Z",
      "email": "alice@prisma.io",
      "id": 1,
      "name": "Alice"
    },
    "authorId": 1,
    "content": "",
    "createdAt": "2021-03-02T17:09:53.160Z",
    "id": 1,
    "published": true,
    "title": "Prisma with Azure",
    "updatedAt": "2021-03-03T10:07:11.047Z"
  }
]

Developing and debugging the functions locally

When implementing Azure Functions, you can also start a local development environment using the Azure Functions Core tools' function runtime. That way, you can test and debug the implementation of the functions locally.

To launch the functions runtime, run the following command:

npx func start

The command starts a local server and allows you to call any of the functions in the project.

You can inject environment variables into the functions by adding them to the Values object in the local.settings.json file at the root of the project.

Setting up a local database for development

When developing locally, you should consider running a local Microsoft SQL Server instance. While Microsoft SQL Server is not the same as Azure SQL, the two have high compatibility with each other..

The quickest way to set up a local Microsoft SQL Server is with Docker. Check out the Microsoft SQL Server example for more information on how to set it up.

Bootstrapping a new function

When you want to create a new function, you can use the following command to bootstrap a new function:

npx func function new --language JavaScript --template "HTTP trigger" --name FUNCTION_NAME

The command creates a folder with the index.js and function.json files.

Summary

Congratulations! You have successfully deployed the REST API to Azure Functions and used Prisma Client to handle database queries to the Azure SQL database.

For more insight into Prisma Client's API, explore the function handlers and check out the Prisma Client API Reference

It's worth noting that while this guide used the Azure CLI to create all the resources, this can also be achieved via the Azure Portal UI or the VSCode extension, which supports deployments directly from VSCode.

As a next step, you could look into implementing a continuous delivery pipeline using GitHub Actions to automate the deployment process from a GitHub repository.

Productive Development With Prisma’s Zero-Cost Type Safety

Daniel Norman — Tue, 09 Jun 2020 11:49:39 +0000

Handling data is at the core of web applications and comes with many challenges as data travels through different components of the application's code.
In this article, we'll look at Prisma's zero-cost type safety and how it boosts productivity and increases developer confidence in applications that use a relational database.

The journey of data in web applications

If you've been building web applications, there's a good chance you've spent a lot of your time handling data. As a developer, your concerns with data start in the UI, as users enter information or interact in a way that creates information. This is where the long data journey begins. The journey usually ends in a database; from which it may go on many more journeys as it's fetched, updated, and saved again.

💡 The post assumes a basic understanding of relational databases and full-stack development.

In a typical three-tier application, the journey looks as follows:

The data is sent via HTTP from the user's browser by the frontend to the backend server (or a serverless function) via an API, for example a GraphQL or REST API.
The backend finds the matching route and its handler.
The backend authenticates the user, deserializes the data, and validates the data.
The route handler applies business logic to the data.
The database access layer is used to safely store the data in the database.

Each of the components that the data moves through may manipulate and transform the data. With JavaScript, there's a common problem when multiple components interact with data: type errors.

A type error is an error that occurs when a value in an operation is of a different type from what the code expects.

For example, a function that concatenates the first and last name of a user object may run into a type error:

function getFullName(user) {
  return `${user.firstName} ${user.lastName}`
}

Calling the function without passing in a parameter raises a type error:

getFullName() // Uncaught TypeError: Cannot read property 'firstName' of undefined

Calling the function with an object missing the properties will not raise an error:

getFullName({}) // "undefined undefined"

getFullName({ firstName: 'Shakuntala' }) // "Shakuntala undefined"

This is due to JavaScript's ability to convert types during runtime. In this case, undefined is converted to string. This feature is known as implicit type coercion.

With JavaScript, these errors occur at runtime. In practice, this means that these errors are discovered during testing or after the application has been deployed.

Type safety with TypeScript

In recent years, TypeScript became popular amongst JavaScript developers as a typed language that compiles to JavaScript. One of the main benefits that TypeScript offers is the ability to detect type errors at compile time which increases confidence in the applications you're building.

For example, we can define the getFullName function from above as follows:

function getFullName (user: {firstName: string, lastName: number}) => (
  return `${user.firstName} ${user.lastName}`
)

getFullName({}) // Type error

Since the call below the function definition is invalid, the error will be caught when the TypeScript compiler is run:

$ tsc example.ts

example.ts:5:13 - error TS2345: Argument of type '{}' is not assignable to parameter of type '{ firstName: string; lastName: number; }'.
  Type '{}' is missing the following properties from type '{ firstName: string; lastName: number; }': firstName, lastName

5 getFullName({})

Benefits of TypeScript aside, when comparing TypeScript to JavaScript, it comes at a cost of defining types which often reduces productivity.

Changing data and type errors

Type errors are especially common during rapid development and prototyping where introducing new features requires changes to the structure of the data.

For example, a blog may have the concept of Users and Posts, whereby, an author can have many posts. Typically, each of these two entities would have a structure like in the following diagram:

If you decide to rename the name field to firstName and add a lastName field you will need to update the database schema. But once the database schema has been migrated (updated to have a new structure), the backend may fail as its queries still point to the name field which doesn't exist.

This kind of change is called a schema migration, and there are many ways to deal with such changes. For example, the naive approach could look as follows:

You schedule a maintenance window and use the time before to:

Update the backend code to use the new field.
Migrate the database schema in a test environment.
Test the updated backend with the migrated database schema.
If the testing succeeds, use the maintenance window to take down the old version of the backend, migrate the database schema, and then deploy the updated backend.

One of the problems with this approach (besides having to take the service down) is that updating the code to use the new field is a manual process. Because code accessing the old name field is still syntactically valid, type errors will happen when the code runs. Specifically, no error will be thrown, as accessing undefined fields doesn't throw a TypeError like in the getFullName example above.

Adapting the code to the new schema can be done in a couple of ways, which can be combined:

Manually searching the code for all occurrences of name and adjusting them to work with the schema change.
With unit and integration tests. You can start the process by creating new tests to describe the expected behavior after the change. The tests fail initially and as the code is updated, they gradually pass as the code is adapted to make use of the new fields.

Depending on how you're accessing your database, either approach can be a cumbersome task. With an SQL query builder like knex.js, you have to search for queries using the old name field and update them. With ORMs, you typically have to update the User model and ensure the model isn't used to access or manipulate the old name field.

In an application using knex.js, the change looks as follows:

const user = await db('users')
-  .select('userId', 'name', 'twitter', 'email)
+  .select('userId', 'firstName', 'lastName', 'twitter', 'email)
  .where({
    userId: requestedUserId
  })

await db('users')
  .where({ userId: userIdToUpdate })
-  .update({ name: newName })
+  .update({ firstName: newFirstName, lastName: newLastName })

The challenge here, irrespective of the specific database abstraction is that you need to coordinate changes between the database and your codebase.

Prisma approach eases the coordination work between the codebase and the database schema.

Prisma – modern database toolkit

Prisma 2 is an open-source database toolkit that was built with the benefits of type safety in mind.

In this post, we'll look at Prisma Client, the toolkit's type-safe database client for Node.js and TypeScript.

💡 Prisma Migrate, the Prisma's migration tool is currently in an experimental state. For more information, check out the Prisma Migrate documentation

Prisma is database agnostic and supports different databases including PostgreSQL, MySQL, and SQLite.

The generated Prisma Client is in TypeScript, which makes type safety possible. **The good news is that you can reap some of the rewards of type safety in a Node.js application written in JavaScript without having to invest the time defining types for the database layer.

Moreover, Prisma can serve as a gateway to a deeper understanding of TypeScript's benefits.

Schema centric workflow

Prisma uses the Prisma schema as a declarative and typed schema for your database. It serves as the source of truth for both the database and the client, which is auto-generated from the Prisma schema. The Prisma schema is just another representation of your database. For the example above, the corresponding Prisma schema would look as follows:

model User {
  id      Int     @default(autoincrement()) @id
  email   String  @unique
  name    String?
  twitter String?
  posts   Post[]
}

model Post {
  postId   Int     @default(autoincrement()) @id
  title    String
  content  String?
  author   User?   @relation(fields: [authorId], references: [id])
  authorId Int?
}

Prisma supports different workflows depending on whether you are starting from scratch or with an existing database.

Assuming you have a database schema already defined (with SQL or with a migration tool), Prisma's workflow looks as follows from a high level:

You introspect the database using the Prisma CLI which creates the Prisma schema.
You use the CLI to generate the Prisma Client (which uses the Prisma schema as a representation of the database schema). You get a node module that is tailored to your database schema.

With the database introspected and the Prisma Client generated, you can now use Prisma Client as follows:

import { PrismaClient } from '@prisma/client'

const prisma = new PrismaClient()

// An example route handler for POST /api/user
// Required fields in body: name, email
export default async function handle(req, res) {
  const { name, email } = req.body
  const createdUser = await prisma.user.create({
    data: {
      name,
      email,
    },
  })

  res.json({
    id: createdUser.id,
    name: createdUser.name,
    email: createdUser.email,
  })
}

The appeal of generated Prisma Client (as imported from @prisma/client) is that all input parameters and return values of the prisma methods are fully typed. For example, in VSCode you can right-click on createdUser and Go to Type Definition which will lead to the generated TypeScript code:

export type User = {
  id: number
  email: string
  name: string | null
  twitter: string | null
}

Because of those types, it's possible for tooling, e.g. code editors and CLI tools to do a lot of checks behind the scenes and provide you with actionable feedback as you're writing code. For example, trying to access a non-existent field, e.g. createdUser.address would be quickly detectable and could be notified.

With a better understanding of the relationship between the database schema, the Prisma schema, and the generated Prisma Client, let's look at the tools that provide such actionable feedback with JavaScript by using the generated types behind the scenes.

Productive and safe development with zero-cost type safety

The benefits of type safety can be had at zero cost in a project using JavaScript with Prisma. This means that you become more confident in your code without any additional effort.

There are several levels to it.

Level 1: Autocomplete suggestions

The first example of zero-cost type safety is the way that VSCode IntelliSense suggestions pop up as you type:

Autocomplete in action

The generated @prisma/client is a CRUD API that is tailored to your database schema and is fully typed in TypeScript. This allows VSCode's IntelliSense to give typed autocomplete suggestions during development.

Level 2: Type safety validations in VSCode

Suggestions are a nice feature that improves productivity and reduces juggling between reading documentation and coding. You can get errors –the same way linters work in VSCode– when your code uses the Prisma API in unintended ways, thereby violating types.

Add // @ts-check to the top of JavaScript files which use the Prisma Client. VSCode will run your code through the TypeScript compiler and report back errors:

With @ts-check the input parameters `prisma.user.create()` and the return value `createdUser` are typed and match the DB field types

If you narrow the returned fields with select in the call to prisma.user.create() the returned createdUser will be typed accordingly:

Selection set and type errors when accessing unselected fields

For this to work enable syntax checking in VSCode:

Set javascript.validate.enable to true in your VSCode configuration:

{
  "javascript.validate.enable": true
}

While this provides valuable feedback during development, nothing stops you from committing or deploying code with errors. This is where automated type checks can be useful.

Level 3: Automated type checks in CI

In a similar fashion to how VSCode runs the TypeScript compiler for type checks, you can run the type checks in your CI or as a commit hook.

Add the TypeScript compiler as a development dependency:

npm install typescript --save-dev

Run the TypeScript compiler:

npx tsc --noEmit --allowJs --checkJs pages/api/*.js

To run as a commit hook:

Husky allows you to define commit hooks in your package.json

You can install Husky:

npm install husky --save-dev

And add the hook:

{
  // package.json
  "husky": {
    "hooks": {
      "pre-commit": "tsc --noEmit --allowJs --checkJs pages/api/*.js"
    }
  }
}

Conclusion

Type errors are a common problem in JavaScript and because they are noticed at runtime, detecting can be difficult without rigorous testing. When working with data that travels through many components and a database, the risk associated with such type errors increases.

TypeScript's type safety alleviate some of those risks but come at a cost of learning TypeScript and defining types upfront.

In applications that rapidly change to accommodate for new features, the database schema must be adapted with schema migrations and in turn the application code.

Having to manually manage such migrations can be error-prone and cumbersome, which reduces the ability to iterate on an application quickly without introducing errors.

Prisma addresses these challenges with a schema centric workflow and an auto-generated TypeScript database client. These features make for a pleasant developer experience as they boost productivity and increase confidence, with autocompletion and automated type checks during build time.

These benefits come at zero cost because as a developer you are not required to take any extra precautions or steps to benefit from type safety using Prisma. Most importantly, all of this is available in projects written exclusively in JavaScript.