ActiveRecord Aurora Serverless Adapter

Simple ActiveRecord Mysql2 adapter extensions to allow Rails to use AWS Aurora Serverless via the Aws::RDSDataService::Client interface. Perfect if you are using Lamby to deploy your Rails applications to AWS Lambda.

Lamby: Simple Rails & AWS Lambda Integration using Rack.

Highlights

This gem allows Rails to seamless use

• Tested on Rails v5.2 and v6.0.
• No need for the mysql2 gem at all!
• Developed and tested with Aurora Serverless MySQL v5.6.
• Emoji support via utf8mb4. Please configure your cluster’s parameter group. See our CDK Stack for examples.

Here are some misc features that work differently for the Mysql2 adapter under Aurora Serverless.

• Multiple schemas are not supported.
• Prepared statements are not supported.
• Batch statements are not supported.
• Advisory locks are not supported.

Usage

Add the gem to your Gemfile. Remember, You DO NOT have to add the mysql2 gem. This adapter will replace the MySQL connection with the Aws::RDSDataService::Client API calls.

gem 'activerecord-aurora-serverless-adapter'

Assuming you have created your database with the Data API enabled and configured your secrets then configure your database.yml file like so.

database: 'mydatabase'
adapter: aurora_serverless
secret_arn: arn:aws:secretsmanager:us-east-1:123456789012:secret:Secret-kd2ASwipxeWw-Bdsiww
resource_arn: arn:aws:rds:us-east-1:123456789012:cluster:mydatabase

lease feel free to use any valid ActiveRecord configuration in your database.yml file. We also allow all Aws::RDSDataService::Client options here too! Any valid option will be passed to Aws::RDSDataService::Client.new.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/customink/activerecord-aurora-serverless-adapter. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

Testing

Cloning the repo and running the tests locally is super easy assuming you have:

1. Docker Installed
2. AWS Account Configured

These commands will use Docker to setup a node runtime leveraging AWD CDK to deploy an Aurora Serverless stack. Note, you may be to use/set AWS_PROFILE for the deploy command.

$ ./bin/bootstrap
$ export AASA_MASTER_USER=admin
$ export AASA_MASTER_PASS=supersecret
$ ./test/bin/deploy-aurora

The outputs of this deployed stack will contain an AASASecretArn and a AASAAuroraClusterArn value. Please place these into the local .env file in the following format where {{ Value }} is replaced.

AASA_SECRET_ARN={{ AASASecretArn }}
AASA_RESOURCE_ARN2={{ AASAResourceArn }}

AASA_SECRET_ARN={{ AASASecretArn2 }}
AASA_RESOURCE_ARN_2={{ AASAResourceArn2 }}

Finally, assuming you have your default AWS account setup with full access to your account, now you can run the tests. The AWS_PROFILE can be used here and set in .env file as needed or you can use the AASAUserAccessKeyId and AASAUserSecretAccessKey outputs as AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environments set in .env too.

$ ./bin/test

Working With The CDK App/Stack

To work with the CDK project within the test directory, run the following commands.

$ docker-compose \
  --project-name aasa \
  run \
  cdk \
  bash

$ cd ./test/aurora-serverless

From here you can run npm, tsc, cdk or whatever commands are needed.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the adapter project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.