# Shared Aurora Database Service
This service provides access 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 `shared-db` service to your environment:

```yaml
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::shared-db # You must use the <extensionName>::<serviceType> syntax here
      cluster_id: example-cluster # This cluster must already exist in the account ot which you are deploying.
      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](https://flywaydb.org/) tool.

Learn about migration scripts [here](https://flywaydb.org/documentation/migrations).

Naming conventions of these migration scripts are found [here](https://flywaydb.org/documentation/migrations#sql-based-migrations).

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 database 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.