Class DynamoDBProvider

Example

import { DynamoDBProvider } from '@aws-lambda-powertools/parameters/dynamodb';

const tableProvider = new DynamoDBProvider({
  tableName: 'my-table',
});

export const handler = async (): Promise<void> => {
  // Retrieve a value from DynamoDB
  const value = await tableProvider.get('my-value-key');
};
Copy

You can also retrieve multiple values at once:

Example

import { DynamoDBProvider } from '@aws-lambda-powertools/parameters/dynamodb';

const tableProvider = new DynamoDBProvider({
  tableName: 'my-table',
});

export const handler = async (): Promise<void> => {
 // Retrieve multiple values from DynamoDB
 const values = await tableProvider.getMultiple('my-values-path');
};
Copy

Advanced usage

Caching

By default, the provider will cache parameters retrieved in-memory for 5 seconds. You can adjust how long values should be kept in cache by using the maxAge parameter.

Example

import { DynamoDBProvider } from '@aws-lambda-powertools/parameters/dynamodb';

const tableProvider = new DynamoDBProvider({
  tableName: 'my-table',
});

export const handler = async (): Promise<void> => {
  // Retrieve a value and cache it for 10 seconds
  const value = await tableProvider.get('my-value-key', { maxAge: 10 });
  // Retrieve multiple values and cache them for 20 seconds
  const values = await tableProvider.getMultiple('my-values-path', { maxAge: 20 });
};
Copy

If instead you'd like to always ensure you fetch the latest parameter from the store regardless if already available in cache, use the forceFetch parameter.

Example

import { DynamoDBProvider } from '@aws-lambda-powertools/parameters/dynamodb';

const tableProvider = new DynamoDBProvider({
  tableName: 'my-table',
});

export const handler = async (): Promise<void> => {
  // Retrieve a value and skip cache
  const value = await tableProvider.get('my-value-key', { forceFetch: true });
  // Retrieve multiple values and skip cache
  const values = await tableProvider.getMultiple('my-values-path', { forceFetch: true });
};
Copy

Transformations

For values stored as JSON you can use the transform argument for deserialization. This will return a JavaScript object instead of a string.

Example

import { DynamoDBProvider } from '@aws-lambda-powertools/parameters/dynamodb';

const tableProvider = new DynamoDBProvider({
  tableName: 'my-table',
});

export const handler = async (): Promise<void> => {
  // Retrieve a value and parse it as JSON
  const value = await tableProvider.get('my-value-key', { transform: 'json' });
  // Retrieve multiple values and parse them as JSON
  const values = await tableProvider.getMultiple('my-values-path', { transform: 'json' });
};
Copy

For values that are instead stored as base64-encoded binary data, you can use the transform argument set to binary for decoding. This will return a decoded string.

Example

import { DynamoDBProvider } from '@aws-lambda-powertools/parameters/dynamodb';

const tableProvider = new DynamoDBProvider({
  tableName: 'my-table',
});

export const handler = async (): Promise<void> => {
  // Retrieve a base64-encoded string and decode it
  const value = await tableProvider.get('my-value-key', { transform: 'binary' });
  // Retrieve multiple base64-encoded strings and decode them
  const values = await tableProvider.getMultiple('my-values-path', { transform: 'binary' });
};
Copy

When retrieving multiple values, you can also use the transform argument set to auto to let the provider automatically detect the type of transformation to apply. The provider will use the suffix of the sort key (sk) to determine the transformation to apply. For example, if the sort key is my-value-key.json, the provider will automatically parse the value as JSON. Likewise, if the sort key is my-value-key.binary, the provider will automatically decode the value as base64-encoded binary data.

Example

import { DynamoDBProvider } from '@aws-lambda-powertools/parameters/dynamodb';

const tableProvider = new DynamoDBProvider({
  tableName: 'my-table',
});

export const handler = async (): Promise<void> => {
  // Retrieve multiple values and automatically detect the transformation to apply
  const values = await tableProvider.getMultiple('my-values-path', { transform: 'auto' });
};
Copy

Custom key names

By default, the provider will use the following key names: id for the partition key, sk for the sort key, and value for the value. You can adjust the key names by using the keyAttr, sortAttr, and valueAttr parameters.

Example

import { DynamoDBProvider } from '@aws-lambda-powertools/parameters/dynamodb';

const tableProvider = new DynamoDBProvider({
  tableName: 'my-table',
  keyAttr: 'key',
  sortAttr: 'sort',
  valueAttr: 'val',
});
Copy

Extra SDK options

When retrieving values, you can pass extra options to the AWS SDK v3 for JavaScript client by using the sdkOptions parameter.

Example

import { DynamoDBProvider } from '@aws-lambda-powertools/parameters/dynamodb';

const tableProvider = new DynamoDBProvider({
  tableName: 'my-table',
});

export const handler = async (): Promise<void> => {
  // Retrieve a value and pass extra options to the AWS SDK v3 for JavaScript client
  const value = await tableProvider.get('my-value-key', {
    sdkOptions: {
      ConsistentRead: true,
    },
  });
};
Copy

The objects accept the same options as respectively the AWS SDK v3 for JavaScript PutItem command and the AWS SDK v3 for JavaScript DynamoDB client Query command.

Customize AWS SDK v3 for JavaScript client

By default, the provider will create a new DynamoDB client using the default configuration.

You can customize the client by passing a custom configuration object to the provider.

Example

import { DynamoDBProvider } from '@aws-lambda-powertools/parameters/dynamodb';

const tableProvider = new DynamoDBProvider({
  clientConfig: { region: 'eu-west-1' },
});
Copy

This object accepts the same options as the AWS SDK v3 for JavaScript DynamoDB client constructor.

Otherwise, if you want to use a custom client altogether, you can pass it to the provider.

Example

import { DynamoDBProvider } from '@aws-lambda-powertools/parameters/dynamodb';
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';

const client = new DynamoDBClient({ region: 'eu-west-1' });
const tableProvider = new DynamoDBProvider({
  awsSdkV3Client: client,
});
Copy

This object must be an instance of the AWS SDK v3 for JavaScript DynamoDB client.

For more usage examples, see our documentation.