onetable-migrate

library1.2.1jsnpmunverified

A migration library for DynamoDB OneTable that supports database schema and content mutations via discrete, reversible migrations. Current stable version is 1.2.1, released on an as-needed basis. Key differentiators include support for both upward/downward migrations and named migrations, ability to seed/remove data, quick dev reset, and persistence of migration history in the table. No module dependencies beyond OneTable, works with AWS SDK v2 and v3, and integrates with SenseDeep Studio and OneTable CLI.

database

npm install onetable-migrate

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ONETABLE-MIGRATE

onetable-migrate

databasejavascriptv1.2.1

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.

Migrate

✓ import { Migrate } from 'onetable-migrate'

✗ import Migrate from 'onetable-migrate'

Default export does not exist; the export is named.

Migrate

✓ const { Migrate } = require('onetable-migrate')

✗ const Migrate = require('onetable-migrate')

CommonJS require returns the module object; destructure the named export.

Table

✓ import { Table } from 'dynamodb-onetable'

Table is a peer dependency from dynamodb-onetable.

Initializes Migrate with a DynamoDB client and OneTable Table, then loads migrations from a directory and prints status.

import { DynamoDBClient } from '@aws-sdk/client-dynamodb'; import { Table } from 'dynamodb-onetable'; import { Migrate } from 'onetable-migrate'; const OneTableParams = { client: new DynamoDBClient({ region: 'us-east-1' }), name: 'MyTable', }; const migrate = new Migrate(OneTableParams, { dir: './migrations' }); await migrate.init(); const status = await migrate.status(); console.log('Migration status:', status);

Debug

Known issues

gotchaMigrate constructor must be called with OneTableParams (Table-like object) after Table has been instantiated with DynamoDB client.

fix

Ensure you pass the same params as used to create a Table instance, including client and table name.

affects: >=1.0.0

breakingIn v1.1.0, the `init()` method is required before calling other methods like `status()` or `up()`. Previously it was optional.

fix

Add `await migrate.init()` after constructing Migrate.

affects: >=1.1.0

deprecatedThe `params.aws` options for AWS SDK v2 are deprecated and will be removed in the next major version.

fix

Use the `client` parameter directly with a DynamoDBClient (v3) or DocumentClient (v2) instead of passing aws region/credentials.

affects: >=1.2.0

gotchaMigration files must export a default object with `up` and `down` async functions. Named exports are not supported.

fix

Use `export default { up, down, ... }` in each migration file.

affects: >=1.0.0

gotchaWhen using `dir` option, migration files are expected to be in CommonJS or ESM format that Node.js can require/import. .mjs files may require additional configuration.

fix

Use .js or .cjs extension for CommonJS, or .mjs for ESM if package.json type is 'module'.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: migrate.init is not a function

Migrate.prototype.init does not exist in older versions (<1.1.0).

fix

Upgrade to version >=1.1.0 or remove the call to init if you're on an older version.

ImportError: must use import to load ES module: /path/to/migration.mjs require() of ES modules is not supported.

Migration file uses ESM syntax but Node.js is configured to treat all .js as CommonJS.

fix

Set package.json type to 'module' or rename migration file extension to .mjs.

Error: Table name 'MyTable' not found in OneTableParams

Missing or incorrect table name parameter in the OneTableParams object.

fix

Ensure OneTableParams includes a 'name' property corresponding to the DynamoDB table name.

ValidationError: The param 'dir' should be a string or array of strings

Invalid value passed to the `dir` option in Migrate constructor (e.g., number, object, etc.).

fix

Pass a string path or an array of string paths to the `dir` option.

Upgrade

Version history

1.2.1latest on npm

Audit

Dependencies

dynamodb-onetablerequiredRequired peer dependency; Migrate is built on top of OneTable's Table.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/sensedeep/onetable-migrate ↗

packageonetable-migrate ↗

homepagehttps://github.com/sensedeep/onetable-migrate ↗