Registry / aws / onetable-cli

onetable-cli

library1.3.5jsnpmunverified

The OneTable CLI is a command-line interface tool designed to orchestrate DynamoDB migrations specifically for applications utilizing `dynamodb-onetable` and `onetable-migrate`. Currently at version 1.3.5, it receives frequent minor patch releases for bug fixes and dependency updates, with major feature releases occurring less often to introduce new capabilities like named migrations (v1.3.0). It serves as a crucial utility for development teams to initialize, reset, and evolve DynamoDB schema and data, and for production environments to manage step-wise database upgrades, downgrades, and maintenance tasks. Its key differentiators include supporting reversible, versioned, and named migrations, operating on both local and remote DynamoDB instances, and facilitating the successful evolution of single-table DynamoDB patterns by allowing automated and ordered sequencing of schema changes and data seeding.

aws database devops

npm install onetable-cli

github ↗package ↗

INSTALL

IMPORT

SIG · ONETABLE-CLI

onetable-cli

awsjavascriptv1.3.5

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

loadModel

✓ import { loadModel } from 'onetable-cli/util/model';

While primarily a CLI, `onetable-cli` exports some internal utilities like `loadModel` for programmatic access to parts of its logic, though this is not typical usage.

loadSchema

✓ import { loadSchema } from 'onetable-cli/util/schema';

Exposes internal functions for loading schema definitions, potentially useful for advanced programmatic interaction.

upgradeSchema

✓ import { upgradeSchema } from 'onetable-cli/util/upgrade';

Provides access to the schema upgrade logic if one were to build custom tooling on top of `onetable-cli`'s internal components.

This quickstart demonstrates how to install the CLI globally, set up a migration directory with a `migrate.json5` configuration file, initialize the migration system, create a new migration stub, and then run it in dry-run mode before applying it.

npm i onetable-cli -g mkdir ./migrations echo "{\n onetable: {\n name: 'your-dynamo-table',\n partial: true\n },\n dir: './migrations'\n}" > migrate.json5 onetable init onetable create my-first-migration onetable up --dry-run onetable up

onetable --version

Debug

Known issues

breakingThe `onetable-migrate` library (used internally by the CLI) now persists migrations to the DynamoDB table and requires each migration to specify its schema. The `--schema` option and `migrate.json` schema property have been removed as the CLI can now read the schema directly from the table.

fix

Remove `--schema` flags and `schema` properties from your `migrate.json` (or `migrate.json5`). Ensure your migration files define their respective schemas as required by `onetable-migrate`.

affects: >=1.2.0

gotchaUsing `--dir` to specify migration file locations is now the preferred method, as it allows for automatic indexing of both versioned and named migrations, even for AWS-hosted migrations.

fix

Always use the `dir` property in your `migrate.json5` configuration to point to your migration directory. This ensures proper indexing and discovery of all migration types.

affects: >=1.3.0

gotchaFor optimal performance, especially with large migrations, it is recommended to host your migrations (via `onetable-controller`) in the same AWS region and availability zone as your DynamoDB table. Executing locally can incur significant I/O transfer time.

fix

Consider deploying the `onetable-controller` solution to remotely host your migrations. Configure your CLI to interact with the remote controller for improved efficiency.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Table not found: your-dynamo-table

The configured DynamoDB table name in `migrate.json5` does not exist or the AWS credentials do not have permission to access it.

fix

Verify the `name` property in `migrate.json5` matches an existing DynamoDB table. Ensure your AWS credentials (via `AWS_PROFILE` or environment variables) have the necessary permissions to `dynamodb:DescribeTable` and other relevant actions.

Error: OneTable configuration missing or invalid in migrate.json5

The `onetable` property in `migrate.json5` is either missing, malformed, or lacks critical configuration like the table `name`.

fix

Check your `migrate.json5` file. Ensure it's valid JSON5 and contains a top-level `onetable` object with at least a `name` property for your DynamoDB table.

Error: Migration failed: An outstanding migration must be run first.

You are trying to run a specific migration or a 'down' migration, but there are unapplied 'up' migrations or the migration history is inconsistent.

fix

Run `onetable status` to inspect the migration state. Use `onetable up` to apply any outstanding migrations sequentially before attempting specific 'down' or 'goto' commands. If the history is corrupted, you might need to manually inspect or reset it (with caution).

Upgrade

Version history

1.3.5latest on npm

Audit

Dependencies

dynamodb-onetablerequiredCore data mapper library for DynamoDB, which the CLI's migrations are built upon.

onetable-migraterequiredUnderlying library for managing and persisting migrations to the DynamoDB table, used internally by the CLI.

onetable-controlleroptionalRecommended for remote hosting of migration logic within AWS Lambda for optimal performance and proximity to DynamoDB.

Agent activity

12 hits · last 30 days

node

Amazon

Resources

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

packagehttps://www.npmjs.com/package/onetable-cli ↗