This project is a bridge between TypeORM and Aurora Data API. It allows you to migrate to Aurora Data API which is extremely useful is serverless environments by only modifying the connection configuration.
✔ AWS SDK V3
✔ Supports both Postgres and MySQL.
✔ Supports casting (allows using UUID, enums, properly formats date and time columns).
⚠ Data API currently destroys any timezone information returning everything in UTC. Be aware of that when using Postgres 'timestamp with time zone', 'time with time zone' and similar types.
- Enable the Data API on your database
- Install the driver by running either
yarn add typeorm-aurora-data-api-driver
or
npm i --save typeorm-aurora-data-api-driver
- Modify your connection configuration to look similar to this:
const connection = await createConnection({
type: 'aurora-mysql',
database: 'test-db',
secretArn: 'arn:aws:secretsmanager:eu-west-1:537011205135:secret:xxxxxx/xxxxxx/xxxxxx',
resourceArn: 'arn:aws:rds:eu-west-1:xxxxx:xxxxxx:xxxxxx',
region: 'eu-west-1',
serviceConfigOptions: {
// additional options to pass to the aws-sdk RDS client
},
formatOptions: {
// additional format options to pass to the Data API client
}
})
Or if you're using Postgres:
const connection = await createConnection({
type: 'aurora-postgres',
database: 'test-db',
secretArn: 'arn:aws:secretsmanager:eu-west-1:537011205135:secret:xxxxxx/xxxxxx/xxxxxx',
resourceArn: 'arn:aws:rds:eu-west-1:xxxxx:xxxxxx:xxxxxx',
region: 'eu-west-1',
serviceConfigOptions: {
// additional options to pass to the aws-sdk RDS client
},
formatOptions: {
// additional format options to pass to the Data API client
}
})
After you done that you can use the connection just as you did with any other connection:
const postRepository = connection.getRepository(Post)
const post = new Post()
post.title = 'My First Post'
post.text = 'Post Text'
post.likesCount = 4
const insertResult = await postRepository.save(post)
This driver uses the Data API Client. To pass additional options to it, use serviceConfigOptions
and formatOptions
properties.
By default, this driver will try to cast entity fields on insert and update queries using entity metadata and Data API client's type casting.
This allows using UUID and enum columns which wouldn't be possible before. To disable this behavior, set the formatOptions.castParameters
to false.
You can specify casting for query parameters as well. To do that pass an object with properties value
and cast
const dbPost = await postRepository.findOne({
title: {
value: 'f01bdc12-ed72-4260-86aa-b7123f08cab9',
cast: 'uuid',
},
})
Alternative way of automatically cast your UUID ids is to enable automatic casting of UUID (based on regex) by passing enableUuidHack: true
to formatOptions
.
If you want to fix a bug or add a feature for this driver, this section will help you get started. Let's start with a simple case where you don't need to touch any code in the TypeORM itself.
- node.js
- docker
- docker-compose
- Fork this repository on GitHub and check out your fork
- Run
yarn
to install dependencies - Install TypeORM by running
npm i --no-save typeorm
. You can also install a specific version of the ORM. - Run
yarn build
to build the code of the driver itself. You will also need to run this command when you make changes in the files under/src
directory.
After that, you can run tests to validate your setup.
- Start a docker image with a database
For Postgres:
docker-compose -f docker/pg.yml up -d
For MySQL:
docker-compose -f docker/mysql.yml up -d
- Run Functional Tests
For Postgres:
yarn test:pg-func
For MySQL
yarn test:mysql-func
Once you verified that your setup is correct by running tests, it's time to actually make changes you'd like. A perfect start would be writing a test for your scenario.
Some features like adding a connection option would require making changes in both TypeORM and this driver.
To develop against a local TypeORM repository, you'll need to replace the third step from the initial setup section with the following:
- In the driver directory, run
yarn link
- Fork the TypeORM repository and check out your fork
- In the TypeORM directory, run
npm i
to install TypeORM dependencies - In the TypeORM directory, run
npm run package
to build TypeORM package - Under the
build/package
directory in the TypeORM project, run the following command to make sure the TypeORM is not linked:yarn unlink
- Under the
build/package
directory in the TypeORM project, run two following commands:yarn link
andyarn link typeorm-aurora-data-api-driver
- In the driver directory, run
yarn link typeorm
What this will do is create symlinks where the driver will use a locally built TypeORM package and a locally built TypeORM package will use a locally built driver.
<driver repo directory>/node_modules/typeorm -> <typeorm repo directory>/build/package
<typeorm repo directory>/build/package/node_modules/typeorm-aurora-data-api-driver -> <driver repo directory>
Unfortunately, every time you need to make a change in the TypeORM directory you'll need to rerun steps 4-7 which is very slow. Please submit a PR updating this readme if you find a nicer way of doing it.
Thanks goes to these wonderful people (emoji key):
Daniel Pecos Martinez 💻 🐛 |
Calvin 💻 📖 |
This project follows the all-contributors specification. Contributions of any kind welcome!