{"id":17855,"library":"onetable-cli","title":"OneTable CLI","description":"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.","status":"active","version":"1.3.5","language":"javascript","source_language":"en","source_url":"https://github.com/sensedeep/onetable-cli","tags":["javascript","dynamodb","onetable","serverless","aws","nosql","singletable","datamapper","dynamo"],"install":[{"cmd":"npm install onetable-cli","lang":"bash","label":"npm"},{"cmd":"yarn add onetable-cli","lang":"bash","label":"yarn"},{"cmd":"pnpm add onetable-cli","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core data mapper library for DynamoDB, which the CLI's migrations are built upon.","package":"dynamodb-onetable","optional":false},{"reason":"Underlying library for managing and persisting migrations to the DynamoDB table, used internally by the CLI.","package":"onetable-migrate","optional":false},{"reason":"Recommended for remote hosting of migration logic within AWS Lambda for optimal performance and proximity to DynamoDB.","package":"onetable-controller","optional":true}],"imports":[{"note":"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.","symbol":"loadModel","correct":"import { loadModel } from 'onetable-cli/util/model';"},{"note":"Exposes internal functions for loading schema definitions, potentially useful for advanced programmatic interaction.","symbol":"loadSchema","correct":"import { loadSchema } from 'onetable-cli/util/schema';"},{"note":"Provides access to the schema upgrade logic if one were to build custom tooling on top of `onetable-cli`'s internal components.","symbol":"upgradeSchema","correct":"import { upgradeSchema } from 'onetable-cli/util/upgrade';"}],"quickstart":{"code":"npm i onetable-cli -g\nmkdir ./migrations\necho \"{\\n    onetable: {\\n        name: 'your-dynamo-table',\\n        partial: true\\n    },\\n    dir: './migrations'\\n}\" > migrate.json5\nonetable init\nonetable create my-first-migration\nonetable up --dry-run\nonetable up\n","lang":"bash","description":"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."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":">=1.2.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.3.0"},{"fix":"Consider deploying the `onetable-controller` solution to remotely host your migrations. Configure your CLI to interact with the remote controller for improved efficiency.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"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.","cause":"The configured DynamoDB table name in `migrate.json5` does not exist or the AWS credentials do not have permission to access it.","error":"Error: Table not found: your-dynamo-table"},{"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.","cause":"The `onetable` property in `migrate.json5` is either missing, malformed, or lacks critical configuration like the table `name`.","error":"Error: OneTable configuration missing or invalid in migrate.json5"},{"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).","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.","error":"Error: Migration failed: An outstanding migration must be run first."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}