OneTable CLI

1.3.5 verified Thu Apr 23 auth: no javascript

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.

Common errors

error Error: Table not found: your-dynamo-table ↓

cause 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 Error: OneTable configuration missing or invalid in migrate.json5 ↓

cause 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 Error: Migration failed: An outstanding migration must be run first. ↓

cause 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).

Warnings

breaking The `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`.

gotcha Using `--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.

gotcha For 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.

Install

npm install onetable-cli

yarn add onetable-cli

pnpm add onetable-cli

Imports

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.

Quickstart

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