Deploy to AWS Lambda

Define binary targets in Prisma Schema

The Prisma schema should contain the following in the generator block:

binaryTargets = ["native", "rhel-openssl-1.0.x"]

This is necessary because the runtimes used in development and deployment differ. Add the binaryTarget to make the compatible Prisma engine file available.

schema.prisma
1binaryTargets = ["native", "linux-arm64-openssl-1.0.x"]

Prisma CLI binary targets

While we do not recommend running migrations within AWS Lambda, some applications will require it. In these cases, you can use the PRISMA_CLI_BINARY_TARGETS environment variable to make sure that Prisma CLI commands, including prisma migrate, have access to the correct schema engine.

In the case of AWS lambda, you will have to add the following environment variable:

.env
1PRISMA_CLI_BINARY_TARGETS=native,rhel-openssl-1.0.x

Connection pooling

Generally, when you use a Function as a Service (FaaS) environment to interact with a database, every function invocation can result in a new connection to the database. This is not a problem with a constantly running Node.js server. Therefore, it is beneficial to pool database connections to get better performance. You can use Accelerate to solve this issue. For other solutions, see the connection management guide for serverless environments.

Loading environment variables

AWS SAM does not directly support loading values from a .env file. You will have to use one of AWS's services to store and retrieve these parameters. This guide provides a great overview of your options and how to store and retrieve values in Parameters, SSM, Secrets Manager, and more.

Loading required files

AWS SAM uses esbuild to bundle your TypeScript code. However, the full esbuild API is not exposed and esbuild plugins are not supported. This leads to problems when using Prisma in your application as certain files (like schema.prisma) must be available at runtime.

To get around this, you need to directly reference the needed files in your code to bundle them correctly. In your application, you could add the following lines to your application where Prisma is instantiated.

app.ts
1import schema from './prisma/schema.prisma'
2import x from './node_modules/.prisma/client/libquery_engine-rhel-openssl-1.0.x.so.node'
3
4if (process.env.NODE_ENV !== 'production') {
5  console.debug(schema, x)
6}

You will also need to define how to bundle these files with esbuild by adding the following lines to Metadata.BuildProperties in your template.yaml:

template.yaml
1Loader:
2  - .prisma=file
3  - .so.node=file
4AssetNames: '[name]'

This will make sure that files needed by Prisma will be included in the AWS SAM build.

Loading environment variables via a .env file

Your functions will need the DATABASE_URL environment variable to access the database. The serverless-dotenv-plugin will allow you to use your .env file in your deployments.

First, make sure that the plugin is installed:

$npm install -D serverless-dotenv-plugin

Then, add serverless-dotenv-plugin to your list of plugins in serverless.yml:

serverless.yml
1plugins:
2  - serverless-dotenv-plugin

The environment variables in your .env file will now be automatically loaded on package or deployment.

$serverless package

Deploy only the required files

To reduce your deployment footprint, you can update your deployment process to only upload the files your application needs. The Serverless configuration file, serverless.yml, below shows a package pattern that includes only the Prisma engine file relevant to the Lambda runtime and excludes the others. This means that when Serverless Framework packages your app for upload, it includes only one engine file. This ensures the packaged archive is as small as possible.

serverless.yml
1package:
2  patterns:
3    - '!node_modules/.prisma/client/libquery_engine-*'
4    - 'node_modules/.prisma/client/libquery_engine-rhel-*'
5    - '!node_modules/prisma/libquery_engine-*'
6    - '!node_modules/@prisma/engines/**'

If you are deploying to Lambda functions with ARM64 architecture you should update the Serverless configuration file to package the arm64 engine file, as follows:

serverless.yml
1package:
2  patterns:
3    - '!node_modules/.prisma/client/libquery_engine-*'
4    - 'node_modules/.prisma/client/libquery_engine-linux-arm64-*'
5    - '!node_modules/prisma/libquery_engine-*'
6    - '!node_modules/@prisma/engines/**'

If you use serverless-webpack, see Deployment with serverless webpack below.

Deployment with serverless-webpack

If you use serverless-webpack, you will need additional configuration so that your schema.prisma is properly bundled. You will need to:

1. Copy your schema.prisma with copy-webpack-plugin.
2. Run prisma generate via custom > webpack > packagerOptions > scripts in your serverless.yml.
3. Only package the correct Prisma engine file to save more than 40mb of capacity.

$npm install --save-dev webpack webpack-node-externals copy-webpack-plugin serverless-webpack

webpack.config.js
1const nodeExternals = require('webpack-node-externals')
2
3module.exports = {
4  // ... other configuration
5  externals: [nodeExternals()],
6  // ... other configuration
7}

webpack.config.js
1const nodeExternals = require('webpack-node-externals')
2const CopyPlugin = require('copy-webpack-plugin')
3
4module.exports = {
5  // ... other configuration
6  externals: [nodeExternals()],
7  plugins: [
8    new CopyPlugin({
9      patterns: [
10        { from: './node_modules/.prisma/client/schema.prisma', to: './' }, // you may need to change `to` here.
11      ],
12    }),
13  ],
14  // ... other configuration
15}

serverless.yml
1custom:
2  webpack:
3    packagerOptions:
4      scripts:
5        - prisma generate

serverless.yml
1custom:
2  webpack:
3    packagerOptions:
4      scripts:
5        - prisma generate
+        - find . -name "libquery_engine-*" -not -name "libquery_engine-rhel-openssl-*" | xargs rm

serverless.yml
1custom:
2  webpack:
3    packagerOptions:
4      scripts:
5        - prisma generate
+        - find . -name "libquery_engine-*" -not -name "libquery_engine-arm64-openssl-*" | xargs rm

$serverless package

Working with environment variables

While SST supports .env files, it is not recommended. SST recommends using Config to access these environment variables in a secure way.

The SST guide available here is a step-by-step guide to get started with Config. Assuming you have created a new secret called DATABASE_URL and have bound that secret to your app, you can set up PrismaClient with the following:

prisma.ts
1import { PrismaClient } from '@prisma/client'
2import { Config } from 'sst/node/config'
3
4const globalForPrisma = global as unknown as { prisma: PrismaClient }
5
6export const prisma =
7  globalForPrisma.prisma ||
8  new PrismaClient({
9    datasourceUrl: Config.DATABASE_URL,
10  })
11
12if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma
13
14export default prisma