README.md

Adonis DynamoDB

A DynamoDB (Dyngoose) wrapper for AdonisJs.

Dyngoose

What is it?

Dyngoose is a DynamoDB object modeling for Typescript.

Why Dyngoose?

Because it looks like Lucid, you will not be lost. The use of decorators makes it even more attractive.

Docs

You can find all Dyngoose docs here.

Installation

First, install the package using npm or yarn

npm i adonis-dynamodb
# or
yarn add adonis-dynamodb

Next, configure the package by running the following command

node ace configure adonis-dynamodb

Then, add the following namespace to .adonisrc.json file

"namespaces": {
  // ...other namespaces
  "dynamodbTables": "App/Tables" // You can use another namespace.
}

Finally, add the rules for the env variables inside env.ts in your application root:

export default Env.rules({
  // ...other rules
  AWS_REGION: Env.schema.string(),
  AWS_ACCESS_KEY_ID: Env.schema.string(),
  AWS_SECRET_ACCESS_KEY: Env.schema.string(),
})

PS: NEVER share these environment variables.

Usage

Create a new table model

Run the following command to create a table model (it will only create the model file in App/Tables or the namespace of your choice)

node ace dynamo:make Test

By default, the primary key name is id. You can use a custom name by adding a flag to the above command

node ace dynamo:make Test --pk=myPrimaryKey

Create the table(s) on AWS from the model(s)

node ace dynamo:create

This operation may take time. You can also create only one table from a given model by adding the model's name/path.

# Using model's name
node ace dynamo:create Test

# Using model's path (the path is resolved using the namespace defined in .adonisrc.json file as root)
node ace dynamo:create Dir/Test

Delete tables from AWS

You can delete one table from AWS using as follows

# This will delete the table named "Test"
node ace dynamo:drop Test

You can also delete all tables (please be careful when you run this command in production as the drop action is irreversible)

# This will delete all the tables
node ace dynamo:drop

Everytime you run the dynamo:drop command you will be asked if you want to confirm the action.

This command will not delete your models.

Create a new record or update an existing one

Dyngoose will automatically perform an UpdateItem operation if it is possible, to only update the attributes you have changed; but if it is a new record it will perform a PutItem operation.

import Test from 'App/Tables/Test'

const test = await Test.new({
  id: 1
  title: 'Test'
})
await test.save()

// Or
const test = new Test()
test.id = 1
test.title = 'Test'
await test.save()

For more information, please, visit Dyngoose saving docs.

Get an existing record (querying)

// Get record by the primary key
const record = await Test.primaryKey.get({ id: 1 })

if (record) {
  // You need to call toJSON() on the record to get your data serialized.
  console.log(record.toJSON())
}

// Or you can use search() method with filters to get an array of records.
const records = await Test.search({ title: 'Test' }).exec()

records.forEach(record => {
  console.log(record.toJSON())
})

// You can also get all records inside a table using scan() method.
const records = await Test.primaryKey.scan()

records.forEach(record => {
  console.log(record.toJSON())
})

Read more about querying here.

Delete a record

// Get record by the primary key
const record = await Test.primaryKey.get({ id: 1 })

if (record) {
  await record.delete()
}