Migration Guides

Step-by-step instructions for upgrading through breaking changes.

Available Guides

Upgrading to 0.15.0

Version: 0.14.x → 0.15.0
Status: Current

Breaking change in this release:

OpenSearch Index Update Required

Must run update-session-mapping-for-messages.ts BEFORE deployment
Adds new fields to session index for message analytics
If not run first, OpenSearch will auto-index incorrectly

What's New:

Message-level analytics (user/assistant counts, timing metrics)
Message content search in Session Insights
Dedicated message index for fast full-text search
Pre-computed statistics for 10-100x faster analytics

Who's Affected:

All deployments (OpenSearch mapping update required before deployment)
Projects using session analytics
Projects using session insights search

Estimated Time: 30-45 minutes (varies with data volume)

View Complete Guide →

Upgrading to 0.11.0

Version: 0.10.x → 0.11.0
Status: Previous

Breaking changes in this release:

1. OpenSearch Keyword Field Migration

Add new keyword fields to session index for aggregation support
Copy data from text fields to keyword fields for existing sessions
Required for session analytics dashboard

2. User Type Migration

Add user_type field to all chat sessions
Enables filtering sessions by internal vs external users

3. Widget Action Callback Signature Change

Action callbacks now receive context object with element reference
Breaking API change requires updating custom widget code

Who's Affected:

All deployments (data migration required before deployment)
Projects using session analytics
Projects with custom widget actions

Estimated Time: 15-30 minutes (varies with data volume)

View Complete Guide →

Upgrading to 0.5.0

Version: 0.4.x → 0.5.0
Status: Previous

Two breaking changes in this release:

1. Tag System Refactor

DynamoDB schema updates (GSI replacement required)
Tag configuration model changes (chatAppId → usageMode)
Chat app tag enablement configuration

2. Chat Session GSI Update

DynamoDB GSI update for correct session sorting
Composite sort key implementation (chat_app_sk with format chatAppId#source#lastUpdate)

Who's Affected:

All deployments (DynamoDB schema changes required)
Projects using custom tags
Projects querying chat sessions by chat app

Estimated Time: 45-60 minutes (includes 4 CDK deployments + wait times)

View Complete Guide →

How to Use Migration Guides

Before Starting

Check your version:
Terminal window
```
cat .pika-sync.json | grep pikaVersion
```

Commit your work:

git add .
git commit -m "Pre-migration checkpoint"

Run sync in dry-run mode:
Terminal window
```
pika sync --dry-run
```

During Migration

Follow steps exactly in order
Don't skip manual verification steps
Keep the migration guide open for reference
Take breaks between major steps (especially AWS changes)

After Migration

Test thoroughly:
- Verify all features work
- Check custom components
- Test tag functionality

Commit the upgrade:

git add .
git commit -m "Upgraded to version X.X.X"

Migration Checklist Template

Copy this for each migration:

- [ ] Read complete migration guide
- [ ] Check current version
- [ ] Commit all pending changes
- [ ] Run `pika sync --dry-run`
- [ ] Follow migration steps
- [ ] Run tests
- [ ] Verify functionality
- [ ] Commit migration

Need Help?

Stuck? Check the "Common Issues" section in each guide
Questions? Review the Troubleshooting docs
Rollback? Each guide includes rollback instructions

Future Migrations

New migration guides will be added here as breaking changes are introduced. Subscribe to release notifications to stay informed.