cdk-drizzle-migrate

About

This CDK construct library makes it possible to run the drizzle migrate at deploy of your stack time against the RDS or DSQL cluster of your choice. The supported engines are PostgreSQL, MariaDB and MySQL.

This construct library is intended to be used in enterprise environments, and works in isolated subnets.

Requirements

This package assumes you deploy from a unix shell with access to cp, mkdir, and curl.

Version 3 of this package is for Drizzle 1 migration folders and requires drizzle-kit and drizzle-orm 1.0 or later. Use version 2 of this package with Drizzle 0.x migration folders.

Installation

 npm i cdk-drizzle-migrate

You probably will be very unhappy if you don't have esbuild, so as usual in a cdk typescript project make sure that is installed too:

npm i esbuild

And obviously drizzle-kit and drizzle-orm 1.0 or later should be available if you actually want to create migrations.

Usage

RDS and Aurora

Have an RDS database and a secret that stores your db credentials. Usually this will be the root secret for your RDS database:

import { DrizzleMigrate } from "@berenddeboer/cdk-drizzle-migrate"

// Create the DrizzleMigrate construct
const migrator = new DrizzleMigrate(this, "DrizzleMigration", {
  dbSecret: database.secret!,
  migrationsPath: "migrations",
  vpc: vpc,
  vpcSubnets: {
    subnetType: ec2.SubnetType.PRIVATE_ISOLATED,
  },
  cluster: database, // Pass the database instance to allow automatic security group configuration
})

Your secret should look like the standard one created by CDK:

{
  "password": "some-password",
  "dbname": "testdb",
  "engine": "postgres",
  "port": 5432,
  "dbInstanceIdentifier": "some-name",
  "host": "some-name.cvabql2flhit.us-east-1.rds.amazonaws.com",
  "username": "postgres"
}

DSQL

For DSQL there is no secret where credentials are stored. Only IAM access is supported.

Drizzle doesn't really support DSQL, so if you create migrations you will often need to tweak them manually as so little of postgresql is supported.

Migrations

Specify the path where the migrations are stored, migrations in this case.

When this resource is deployed, it will run drizzle-kit migrate for you in the lambda.

The default timeout is 5 minutes, you need to increase this if your migration takes more time.

Passing your database cluster is optional. If supplied, the lambda's security group will be added as allowed source to the database security group if no security group is present in handlerProps.securityGroups.

If you do not pass a cluster, make sure to pass in a security group in handlerProps.securityGroups which can connect to your database.

Also if you do not pass a cluster, but you still want to create a database, you may wish to add a dependency to make sure the database is created, before the migration is run:

migrator.resource.node.addDependency(cluster)

Potential pitfalls

1. The lambda can only run for 15 minutes. If your migrations take longer, this solution will not work.

Working on this code

1. Install packages: npm ci

2. Bootstrap CDK if not done: npx cdk bootstrap aws://123456/us-east-1. Replace 123456 with your AWS account.

Handler notes

When making changes to the Lambda handler code in lambda/index.ts, you need to transpile it to JavaScript:

npx projen build:handler

This will generate src/handler/handler.js which is used by the CDK construct.

This technique is used to avoid having to bundle nodejs dependencies as that doesn't work well in this case.