Skip to content

Get started

Prerequisites

  • Python 3.12+ and uv
  • Claude Code for the full pipeline (schema design and synthesis need a model); Node 22 if you want the local UI
  • No AWS account, no API keys, no Docker required for the steps below

Install

git clone https://github.com/aws-samples/sample-aws-genai-db-modernizer.git
cd sample-aws-genai-db-modernizer
uv sync

Run the sample assessment with Claude Code

The repo ships a WordPress + WooCommerce sample (50 tables, 107 queries) as a zip, so unzip it first:

unzip docs/examples/wordpress/wordpress.zip -d docs/examples/wordpress/

Open the repository in Claude Code and run, with the collector file as the argument:

/modernize docs/examples/wordpress/wordpress-collection.json

By default /modernize opens the local UI next to the chat. The chat reports each phase, and the UI shows the assignment, the schema designs and the full report. When the chat says the UI is ready, open http://localhost:3000.

The run stops once, after Reality Check, for your approval. The chat shows the final engine assignment and asks you to approve it. Outside chat-only mode it first points you to the Sankey and assignment view in the UI. After you approve, the run goes on by itself through Schema Design and Synthesis to the finished deliverables. For a terminal-only run (no browser, or a headless environment), use /modernize docs/examples/wordpress/wordpress-collection.json --mode chat.

The individual commands (/collect, /triage, /analyze, /assign, /reality-check, /design-schema, /synthesize) run one phase at a time. See Use Claude Code on the help site.

Prefer no LLM, or no Claude Code?

uv run python scripts/run_assessment.py --file docs/examples/wordpress/wordpress-collection.json --db wordpress --llm-mode none

runs the deterministic pipeline (Collect through Reality Check) with no credentials and no network calls. See Other ways to run it for the deterministic CLI, Amazon Bedrock, the local UI on its own, and how to analyze your own database.

The one approval point

/modernize stops once for a decision, after Reality Check. The chat shows the final engine assignment: which engines remain after consolidation, how many queries each one serves, and any query that the model's check redirected. It asks you to approve it before Schema Design runs. Outside chat-only mode it also points you to the Sankey and assignment view in the UI, so you can see the full breakdown first.

After you approve, the run goes on by itself, with no more questions, through Schema Design and Synthesis to the finished deliverables: the decision report, the engineering report, the executive PDF and deck, and the UI view. All of them are built from the same report.json. With --auto the approval is automatic and the whole run is unattended.

Next

  • Use Claude Code for the full command reference and how to analyze your own database.
  • Other ways to run it for the deterministic CLI, Amazon Bedrock, or the local UI on its own.