byu-handel-extension

BYU Handel Extension

This repository contains a Handel extension that provides BYU-specific Handel services such as Shared RDS.

If you're looking at this from outside BYU, chances are this won't be useful to you.

Aurora MySQL Service

This service provides acesss to a shared Aurora RDS cluster in each OIT AWS account. Inside this cluster, your application has a database provisioned for it.

Usage

To use this extension, add it to the extensions section of your Handel file, and then add the mysql service to your environment:

version: 1

name: rds-example

extensions: # This tells Handel to import this extension
  byu: byu-handel-extension # This is the NPM package name of this extension

environments:
  dev:
    db:
      type: byu::mysql # You must use the <extensionName>::<serviceType> syntax here
      schema_migrations_dir: ./migrations # Optional. Path to the directory containing your SQL migrations to be run against your database.

Schema Migrations

You can specify schema migrations to be run using the schema_migrations_dir parameter. Currently we support running migrations via the Flyway tool.

To have the deployment run your migrations, add valid Flyway migration scripts to a directory in your repository and point the schema_migrations_dir parameter to it.

Note: Be aware that migrations don't run at the same time as your application code deployment. Depending on the type of migration, they can also take a long time to run. You need to follow good database refactoring techniques if you want to update your database with zero downtime.

Depending on this service

This MySQL service outputs the following environment variables:

Environment Variable	Description
<SERVICE_NAME>_CLUSTER_ENDPOINT	The address you should use for writes to the database
<SERVICE_NAME>_READ_ENDPOINT	The address you should use for reads to the database
<SERVICE_NAME>_DATABASE_NAME	The name of the database in the Aurora cluster.
<SERVICE_NAME>_PORT	The port on which the Aurora cluster is listening.
<SERVICE_NAME>_DDL_USER_SECRET_NAME	The Secrets Manager name of the secret containing the DDL user for your database.
<SERVICE_NAME>_RW_USER_SECRET_NAME	The Secrets Manager name of the secret containing the Read/Write user for your database.

The two SECRET_NAME environment variables tell you where you can go to get the user information for your database. These users are stored in the AWS Secrets Manager service, and your application will need to call the GetSecretValue API call to get the credentials for your database users.