Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jitsecurity/dynamo-data-transform
Dynamo Data Transform is an easy to use data transformation tool for DynamoDB
https://github.com/jitsecurity/dynamo-data-transform
aws dyanmodt dynamo dynamodb migration-tool transform transformation-tool
Last synced: 2 months ago
JSON representation
Dynamo Data Transform is an easy to use data transformation tool for DynamoDB
- Host: GitHub
- URL: https://github.com/jitsecurity/dynamo-data-transform
- Owner: jitsecurity
- License: mit
- Created: 2022-06-02T22:36:45.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-04-11T00:58:40.000Z (9 months ago)
- Last Synced: 2024-10-02T16:38:03.564Z (3 months ago)
- Topics: aws, dyanmodt, dynamo, dynamodb, migration-tool, transform, transformation-tool
- Language: JavaScript
- Homepage:
- Size: 1.35 MB
- Stars: 51
- Watchers: 6
- Forks: 4
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: license
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
- awesome-dynamodb - DynamoDataTransform
- awesome-opensource-israel - DynamoDataTransform - Dynamo Data Transform is an easy to use data transformation tool for DynamoDB    (Projects by main language / javascript)
README
Dynamo Data Transform is an easy to use data transformation tool for DynamoDB.
It allows performing powerful data transformations using simple Javascript commands, without the risk of breaking your database.
Available as a [Serverless plugin](#-serverless-plugin), [npm package](#standalone-npm-package) and even as an [interactive CLI](#-interactive-cli), Dynamo Data Transform saves you time and keeps you safe with features like dry-running a data transformation and even rolling back your last trasnformation if needed.
**Features**
- Seemless data transformations management.
- Support for multiple stages.
- History of executed data transformations.
- Dry run option for each command (by suppling --dry flag, the data will be printed instead of stored).
- Safe & Secure preparation data
- Store preparation data in a private s3 bucket. [Prepare data for your data transformation](#usage-and-command-line-options)
## Table of contents
- [Quick Start](#quick-start)
- [Serverless plugin](#-serverless-plugin)
- [Standalone npm package](#standalone-npm-package)
- [Interactive CLI](#-interactive-cli)
- [Creating your first data transformation](#creating-your-first-data-transformation)
- [Usage and command-line options](#usage-and-command-line-options)
- [What happens behind the scenes](#what-happens-behind-the-scenes)
- [Examples](#examples)
- [The data transformation process](https://github.com/jitsecurity/dynamo-data-transform/blob/main/docs/zero_downtime_data_transformation_process.md)
## Quick Start
### ⚡ Serverless plugin
- Install
```bash
npm install dynamo-data-transform --save-dev
```
- Add the tool to your serverless.yml
Run:
```bash
npx serverless plugin install -n dynamo-data-transform
```
Or add manually to your serverless.yml:
```YML
plugins:
- dynamo-data-transform
```
- Run
```bash
sls dynamodt --help
```
### Standalone npm package
- Install the tool
```bash
npm install -g dynamo-data-transform -s
```
- Run the tool
```bash
dynamodt help
```
Or with the shortcut
```bash
ddt help
```
### 💻 Interactive CLI
After installing the npm package, run:
```bash
dynamodt -i
```
## Creating your first data transformation
1. Intialize data-transformations folder
Serverless (the plugin reads the table names from the serverless.yml file):
```bash
sls dynamodt init --stage
```
Standalone:
```bash
ddt init --tableNames
```
Open the generated data transformation file 'v1_script-name.js' file and implement the following functions:
- transformUp: Executed when running `dynamodt up`
- transformDown: Executed when running `dynamodt down -t `
- prepare (optional): Executed when running `dynamodt prepare -t --tNumber `
The function parameters:
- ddb: The DynamoDB Document client object see [DynamoDB Client](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-dynamodb)
- isDryRun: Boolean indicating if --dry run supplied. You can use it to print/log the data instead of storing it.
- preparationData: if you stored the preparation data using `dynamodt prepare`, you can use it here.
2. Run the data transformation
```bash
dynamodt up
```
## Data Transformation Script Format
Make sure your script name contains the transformation number, for example: v1_transformation_script
```js
const { utils } = require('dynamo-data-transform')
const TABLE_NAME = 'UsersExample'
const transformUp = async ({ ddb, isDryRun, preparationData }) => {
// your code here...
// return { transformed: 50 } // return the number of transformed items
}
const transformDown = async ({ ddb, isDryRun, preparationData }) => {
// your code here...
// return { transformed: 50 } // return the number of transformed items
}
const prepare = async ({ ddb, isDryRun }) => {
// your code here...
// return { transformed: 50 } // return the number of transformed items
}
module.exports = {
transformUp,
transformDown,
prepare, // optional
transformationNumber: 1,
}
```
## Usage and command-line options
List available commands:
Serverless plugin:
```bash
sls dynamodt --help
```
Standalone npm package:
```bash
dynamodt help
```
To list all of the options for a specific command run:
Serverless plugin:
```bash
sls dynamodt --help
```
Standalone npm package:
```bash
dynamodt --help
```
## What happens behind the scenes
- When a data transformation runs for the first time, a record in your table is created. This record is for tracking the executed transformations on a specific table.
## Examples
[Examples of data transformation code](https://github.com/jitsecurity/dynamo-data-transform/tree/main/examples/serverless-localstack/data-transformations/UsersExample)
### Insert records
```js
// Seed users data transformation
const { utils } = require('dynamo-data-transform');
const { USERS_DATA } = require('../../usersData');
const TABLE_NAME = 'UsersExample';
/**
* @param {DynamoDBDocumentClient} ddb - dynamo db document client https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-dynamodb
* @param {boolean} isDryRun - true if this is a dry run
*/
const transformUp = async ({ ddb, isDryRun }) => {
return utils.insertItems(ddb, TABLE_NAME, USERS_DATA, isDryRun);
};
const transformDown = async ({ ddb, isDryRun }) => {
return utils.deleteItems(ddb, TABLE_NAME, USERS_DATA, isDryRun);
};
module.exports = {
transformUp,
transformDown,
transformationNumber: 1,
};
```
### Add a new field to each record
```js
// Adding a "randomNumber" field to each item
const { utils } = require('dynamo-data-transform');
const TABLE_NAME = 'UsersExample';
const transformUp = async ({ ddb, isDryRun }) => {
const addRandomNumberField = (item) => {
const updatedItem = { ...item, randomNumber: Math.random() };
return updatedItem;
};
return utils.transformItems(ddb, TABLE_NAME, addRandomNumberField, isDryRun);
};
const transformDown = async ({ ddb, isDryRun }) => {
const removeRandomNumberField = (item) => {
const { randomNumber, ...oldItem } = item;
return oldItem;
};
return utils.transformItems(ddb, TABLE_NAME, removeRandomNumberField, isDryRun);
};
module.exports = {
transformUp,
transformDown,
transformationNumber: 2,
};
```
For more examples of data transformation code, see the [examples](https://github.com/jitsecurity/dynamo-data-transform/tree/main/examples/serverless-localstack/data-transformations/UsersExample) folder in the repository.
Read how to automate data-transformation process here:
https://www.infoq.com/articles/dynamoDB-data-transformation-safety/