{"id":47385,"library":"ddb-migrations","title":"ddb-migrations","description":"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.","status":"active","version":"1.0.4","language":"javascript","source_language":"en","source_url":null,"tags":["javascript"],"install":[{"cmd":"npm install ddb-migrations","lang":"bash","label":"npm"},{"cmd":"yarn add ddb-migrations","lang":"bash","label":"yarn"},{"cmd":"pnpm add ddb-migrations","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required to interact with DynamoDB and store migration state","package":"aws-sdk","optional":false}],"imports":[{"note":"ESM since v1? Actually package.json missing 'type':'module', but README shows CJS. Better use CJS.","wrong":"const ddbMigrations = require('ddb-migrations')","symbol":"default","correct":"import ddbMigrations from 'ddb-migrations'"},{"note":"Package exports generateMigration as named export, but not documented clearly; best to use CJS require.","wrong":"import { generateMigration } from 'ddb-migrations'","symbol":"generateMigration","correct":"const { generateMigration } = require('ddb-migrations')"},{"note":"runMigrations is a named export, not default.","wrong":"import runMigrations from 'ddb-migrations'","symbol":"runMigrations","correct":"const { runMigrations } = require('ddb-migrations')"}],"quickstart":{"code":"const { migrate } = require('ddb-migrations');\n\n// Run pending migrations\nmigrate({\n  awsRegion: process.env.AWS_REGION ?? 'eu-west-1',\n  awsAccessKey: process.env.AWS_ACCESS_KEY ?? '',\n  awsSecretKey: process.env.AWS_SECRET_KEY ?? '',\n  migrationTable: '__migrations',\n  path: './migrations'\n}).then(() => console.log('Migrations complete')).catch(err => console.error(err));","lang":"javascript","description":"Shows how to programmatically run pending migrations using the migrate function with AWS credentials from environment variables."},"warnings":[{"fix":"Create the table manually with appropriate capacity before running migrations, or override table name.","message":"The package creates a DynamoDB table named '__migrations' with default read/write capacity of 1, which may be insufficient for production workloads.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure each migration file exports { up: async (awsConfig, ddb, ddbClient) => {...}, down: async (awsConfig, ddb, ddbClient) => {...} }.","message":"Migration files must export an object with 'up' and 'down' async functions. Missing either will cause runtime error.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Use aws-sdk v2 in your project, or consider alternatives that support v3.","message":"The package uses AWS SDK v2 (aws-sdk), which is in maintenance mode and not compatible with AWS SDK v3. No support for v3.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Run migrations sequentially from a single instance, or implement external locking.","message":"Parallel migrations are not atomic; race conditions can occur if multiple instances run concurrently.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use 'db:migrate' for migration operations and 'migration:generate' for generation.","message":"The CLI commands use 'db:migrate' prefix, but documentation also shows 'migration:generate'. Consistent naming not guaranteed.","severity":"deprecated","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'1.0.4':13 'api':29 'appli':38 'aw':4,59 'cli':26 'creat':31 'data':20 'ddb':2,5 'ddb-migrat':1 'depend':55 'differenti':49 'direct':57 'documentcli':65 'dynamodb':9,23,63 'enabl':15 'extern':52 'file':47 'framework':54 'generat':44 'infrequ':70 'javascript':72 'key':48 'lightweight':50 'manag':11,16 'migrat':3,6,10,21,35,39,42,46,53 'programmat':28 'releas':66 'schema':18 'sdk':60 'stabl':68 'state':33 'support':40 'tabl':24,34 'track':37 'up/down':41 'updat':71 'v2':61 'version':12 'via':25 'work':56","created_at":"2026-06-07T16:51:16.042494+00:00","updated_at":"2026-06-07T16:51:16.042494+00:00","problems":[{"fix":"Run 'npm install ddb-migrations --save' in your project directory.","cause":"Package not installed or globally installed but not in local node_modules.","error":"Cannot find module 'ddb-migrations'"},{"fix":"Pass the correct DynamoDB (not DocumentClient) instance to migration functions if using programmatic API.","cause":"Migration function expects DynamoDB instance, but DocumentClient provided instead.","error":"ddb.createTable is not a function"},{"fix":"Ensure the migration table has a primary key named 'id' of type S.","cause":"State table schema mismatch; migration table has different key schema.","error":"ValidationException: The provided key element does not match the schema"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":null,"github":null,"docs":null,"changelog":null,"pypi":null,"npm":"ddb-migrations","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}