Skip to main content

​
Overview

V3 introduces fine-grained permission control and Bot Store functionality, requiring DynamoDB schema changes. This migration guide will help you safely upgrade from V2 to V3 while preserving your data.
Service Disruption NoticeDuring the migration process, the application will be unavailable to all users until completion. This typically takes around 60 minutes, depending on data volume and environment performance.Plan to perform this migration during a maintenance window when users do not need access to the system.
Bot Migration Success RateThe migration process cannot guarantee 100% success for all bots, especially those created with older versions or custom configurations. Document your important bot configurations before migration in case manual recreation is needed.

​
What’s New in V3

V3 introduces significant enhancements:
  1. Fine-grained permission control: Control bot access with user group-based permissions
  2. Bot Store: Share and discover bots through a centralized marketplace
  3. Administrative features: Manage APIs, mark bots as essential, and analyze bot usage

​
Bot Visibility Changes

In V3, all V2 bots with public sharing enabled will be searchable in the Bot Store. If you have bots containing sensitive information, consider making them private before migrating to V3.

​
Prerequisites

Before starting the migration:
  • Access to AWS CLI with appropriate permissions
  • Administrator access to your Bedrock Chat deployment
  • Current CloudFormation stack name (with environment prefix if using multiple environments)
  • Scheduled maintenance window of at least 90 minutes

​
Migration Process

1

Identify Your Environment Name

In this procedure, {YOUR_ENV_PREFIX} identifies your CloudFormation Stack name.If using Deploying Multiple Environments, replace it with your environment name. Otherwise, use an empty string.
2

Update Repository URL (Recommended)

The repository has been renamed from bedrock-claude-chat to bedrock-chat.
# Check current remote URL
git remote -v

# Update the remote URL
git remote set-url origin https://github.com/aws-samples/bedrock-chat.git

# Verify the change
git remote -v
3

Upgrade to Latest V2 Version

You MUST update to v2.10.0 before migrating to V3. Skipping this step may result in data loss during migration.
# Fetch the latest tags
git fetch --tags

# Checkout the latest V2 version
git checkout v2.10.0

# Deploy the latest V2 version
cd cdk
npm ci
npx cdk deploy --all
4

Record V2 DynamoDB Table Name

Save the V2 ConversationTable name from CloudFormation outputs:
# Get the V2 ConversationTable name
aws cloudformation describe-stacks \
  --output text \
  --query "Stacks[0].Outputs[?OutputKey=='ConversationTableName'].OutputValue" \
  --stack-name {YOUR_ENV_PREFIX}BedrockChatStack
Save this table name securely - you’ll need it for the migration script.
5

Backup Your DynamoDB Table

Create a backup of your ConversationTable:
# Create backup
aws dynamodb create-backup \
  --no-cli-pager \
  --backup-name "BedrockChatV2Backup-$(date +%Y%m%d)" \
  --table-name YOUR_V2_CONVERSATION_TABLE_NAME

# Check backup status
aws dynamodb describe-backup \
  --no-cli-pager \
  --query BackupDescription.BackupDetails \
  --backup-arn YOUR_BACKUP_ARN
Wait until the backup status shows “AVAILABLE” before proceeding.
6

Delete All Published APIs

Before deploying V3, you must delete all published APIs to avoid CloudFormation output value conflicts.
  1. Log in to your application as an administrator
  2. Navigate to Admin section → API Management
  3. Review the list of all published APIs
  4. Delete each published API by clicking the delete button
See API Publishing and Administration for more details.
7

Deploy V3

Pull the latest V3 code and deploy:
git fetch
git checkout v3
cd cdk
npm ci
npx cdk deploy --all
Once you deploy V3, the application will be unavailable to all users until the migration script completes. The new schema is incompatible with the old data format.
8

Record V3 DynamoDB Table Names

After deploying V3, get both the new ConversationTable and BotTable names:
# Get V3 ConversationTable name
aws cloudformation describe-stacks \
  --output text \
  --query "Stacks[0].Outputs[?OutputKey=='ConversationTableNameV3'].OutputValue" \
  --stack-name {YOUR_ENV_PREFIX}BedrockChatStack

# Get V3 BotTable name
aws cloudformation describe-stacks \
  --output text \
  --query "Stacks[0].Outputs[?OutputKey=='BotTableNameV3'].OutputValue" \
  --stack-name {YOUR_ENV_PREFIX}BedrockChatStack
Save these V3 table names along with your V2 table name.
9

Run the Migration Script

Edit the migration script docs/migration/migrate_v2_v3.py to set your configuration:
# Region where DynamoDB is located
REGION = "ap-northeast-1"  # Replace with your region

# Table names from Steps 4 and 8
V2_CONVERSATION_TABLE = "BedrockChatStack-DatabaseConversationTableXXXX"
V3_CONVERSATION_TABLE = "BedrockChatStack-DatabaseConversationTableV3XXXX"
V3_BOT_TABLE = "BedrockChatStack-DatabaseBotTableV3XXXXX"
The Python requirements version was updated to 3.13.0 or later. If you have a venv with a different Python version, remove it first.
Run the migration script:
# Navigate to backend directory
cd backend

# Install dependencies
poetry install

# Run dry run first
poetry run python ../docs/migration/migrate_v2_v3.py --dry-run

# Run actual migration
poetry run python ../docs/migration/migrate_v2_v3.py

# Verify migration
poetry run python ../docs/migration/migrate_v2_v3.py --verify-only
The script will generate a report file with migration details. Review this file to ensure all data was migrated correctly.
10

Verify the Application

Open your application and verify:
  • All bots are available
  • Conversations are preserved
  • New permission controls are working
  • Bot Store is accessible

​
Handling Large Data Volumes

For environments with heavy usage or large amounts of data:

​
Migrate Users Individually

For users with large data volumes, migrate them one at a time: 
poetry run python ../docs/migration/migrate_v2_v3.py --users user-id-1 user-id-2

​
Memory Considerations

The migration process loads data into memory. If you encounter Out-Of-Memory (OOM) errors:
  • Migrate one user at a time
  • Run the migration on a machine with more memory
  • Break up the migration into smaller batches of users

​
Monitor the Migration

Check the generated report files to ensure all data is migrated correctly, especially for large datasets.

​
Clean Up (Optional)

After confirming successful migration and verifying all data is accessible in V3: 
# Delete the V2 conversation table (ONLY after confirming successful migration)
aws dynamodb delete-table --table-name YOUR_V2_CONVERSATION_TABLE_NAME
Only delete the V2 table after thoroughly verifying that all important data has been successfully migrated. We recommend keeping the backup for at least a few weeks after migration.

​
V3 Frequently Asked Questions

​
Bot Access and Permissions

Authorization is checked at chat time, so you’ll lose access immediately when permissions are revoked.
Their data can be completely removed by deleting all items from DynamoDB with their user ID as the partition key (PK).
No, an admin must first mark the bot as not essential before turning off sharing.
No, an admin must first mark the bot as not essential before deleting it.

​
Security and Implementation

No, considering the diversity of access patterns. Authorization is performed when accessing bots, and the risk of metadata leakage is considered minimal compared to conversation history.
The bot must be public.
No, authorization is checked using the JWT token to avoid unnecessary I/O operations.

​
Administration

Administrators can:
  • Manage public bots (including checking high-cost bots)
  • Manage APIs
  • Mark public bots as essential
No, only public bots are supported.
  1. Open the Amazon Cognito console and create user groups in the BrChat user pool
  2. Add users to these groups as needed
  3. In BrChat, select the user groups you want to allow access to when configuring bot sharing settings
Note: Group membership changes require re-login to take effect. Changes are reflected at token refresh, but not during the ID token validity period (default 30 minutes in V3).

​
Search Functionality

​
Rollback Procedure

If you need to roll back to V2:
  1. Do not delete your V2 DynamoDB table or backup
  2. Redeploy V2 from the v2.10.0 tag
  3. Restore from the DynamoDB backup if needed
Rolling back will lose any new data created in V3, including new conversations and bot configurations.

​
Next Steps

After successful migration:

Build docs developers (and LLMs) love

Get started for freeTalk to us