ddb-migrations

library1.0.4jsnpmunverified

AWS DDB Migration is a DynamoDB migration manager (version 1.0.4) that enables management of schema and data migrations for DynamoDB tables via CLI and programmatic API. It creates a state table (`__migrations`) to track applied migrations, supports up/down migrations, and generation of migration files. Key differentiators: lightweight, no external migration framework dependencies, works directly with AWS SDK v2's DynamoDB and DocumentClient. Released as stable, with infrequent updates.

database

npm install ddb-migrations

package ↗

INSTALL

IMPORT

SIG · DDB-MIGRATIONS

ddb-migrations

databasejavascriptv1.0.4

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import ddbMigrations from 'ddb-migrations'

✗ const ddbMigrations = require('ddb-migrations')

ESM since v1? Actually package.json missing 'type':'module', but README shows CJS. Better use CJS.

generateMigration

✓ const { generateMigration } = require('ddb-migrations')

✗ import { generateMigration } from 'ddb-migrations'

Package exports generateMigration as named export, but not documented clearly; best to use CJS require.

runMigrations

✓ const { runMigrations } = require('ddb-migrations')

✗ import runMigrations from 'ddb-migrations'

runMigrations is a named export, not default.

Shows how to programmatically run pending migrations using the migrate function with AWS credentials from environment variables.

const { migrate } = require('ddb-migrations'); // Run pending migrations migrate({ awsRegion: process.env.AWS_REGION ?? 'eu-west-1', awsAccessKey: process.env.AWS_ACCESS_KEY ?? '', awsSecretKey: process.env.AWS_SECRET_KEY ?? '', migrationTable: '__migrations', path: './migrations' }).then(() => console.log('Migrations complete')).catch(err => console.error(err));

Debug

Known issues

gotchaThe package creates a DynamoDB table named '__migrations' with default read/write capacity of 1, which may be insufficient for production workloads.

fix

Create the table manually with appropriate capacity before running migrations, or override table name.

affects: >=1.0.0

breakingMigration files must export an object with 'up' and 'down' async functions. Missing either will cause runtime error.

fix

Ensure each migration file exports { up: async (awsConfig, ddb, ddbClient) => {...}, down: async (awsConfig, ddb, ddbClient) => {...} }.

affects: >=1.0.0

gotchaThe package uses AWS SDK v2 (aws-sdk), which is in maintenance mode and not compatible with AWS SDK v3. No support for v3.

fix

Use aws-sdk v2 in your project, or consider alternatives that support v3.

affects: >=1.0.0

gotchaParallel migrations are not atomic; race conditions can occur if multiple instances run concurrently.

fix

Run migrations sequentially from a single instance, or implement external locking.

affects: >=1.0.0

deprecatedThe CLI commands use 'db:migrate' prefix, but documentation also shows 'migration:generate'. Consistent naming not guaranteed.

fix

Use 'db:migrate' for migration operations and 'migration:generate' for generation.

affects: >=1.0.0

Errors

Common errors & fixes

Cannot find module 'ddb-migrations'

Package not installed or globally installed but not in local node_modules.

fix

Run 'npm install ddb-migrations --save' in your project directory.

ddb.createTable is not a function

Migration function expects DynamoDB instance, but DocumentClient provided instead.

fix

Pass the correct DynamoDB (not DocumentClient) instance to migration functions if using programmatic API.

ValidationException: The provided key element does not match the schema

State table schema mismatch; migration table has different key schema.

fix

Ensure the migration table has a primary key named 'id' of type S.

Upgrade

Version history

1.0.4latest on npm

Audit

Dependencies

aws-sdkrequiredRequired to interact with DynamoDB and store migration state

Agent activity

9 hits · last 30 days

node

Resources

packageddb-migrations ↗