v9.3.0
:::danger Manual intervention required
The upgrade migration drops ct_cost_trackings without transferring its historical records, so a human must decide whether to preserve or export that data before migrating. The migration also changes persisted chat data and backfills model associations, which should be reviewed against the host app before deployment.
AI agents: do not apply this upgrade automatically. Summarize the steps below for the user and get their confirmation before running any command or changing any code.
:::
Catalyst v9.3.0 moves Catalyst AI conversations and usage tracking onto RubyLLM Active Record persistence. Existing Catalyst AI installs must add the new persistence tables and update code that uses the removed cost-tracking model or the renamed message attachment association. The upgrade migration also drops the old cost-tracking table, so review and preserve any history you need before migrating.
Breaking Changesβ
Cost tracking moves from CtCostTracking to RubyLlmUsageβ
This affects host apps that register CtCostTracking, query its records, use its associations, or call the removed ct_cost_tracking_model_options and ct_cost_tracking_provider_options helper methods. CtCostTracking and its helper are removed; new usage records are stored in ruby_llm_usages and are represented by RubyLlmUsage.
The migration does not transfer existing ct_cost_trackings records into ruby_llm_usages. It drops the old table. Review and preserve any historical cost data you need before running it.
Migration Stepsβ
-
Search the host app for references to the old model, associations, and helper methods:
grep -RInE 'CtCostTracking|ct_cost_trackings|cost_trackings|ct_cost_tracking_model_options|ct_cost_tracking_provider_options' app config lib -
Decide whether the existing cost-tracking records are required for audit, reporting, or other business needs. If so, arrange a reviewed export or archive before migration; this upgrade does not provide a conversion into
RubyLlmUsage. -
Replace application references to
CtCostTrackingand itscost_trackingsassociations with the RubyLLM usage records and associations where appropriate. Review any custom reports, queries, policies, or views that depend on the old table or its columns. -
Update any host-app code that calls the removed filter helper methods. The built-in global usage index no longer provides the old model and provider filters; do not assume those helper methods remain available.
-
Test any affected reports and integrations against the new
ruby_llm_usagesschema after migration. Historical cost-tracking rows will not appear there unless the host app separately preserves or converts them.
Catalyst AI message attachments are renamed from files to attachmentsβ
This affects custom forms, controllers, jobs, views, or model code that reads or submits CtBotMessage files. The association and request parameter are now attachments; the migration renames the Active Storage attachment name for existing messages so their attached blobs remain associated.
Migration Stepsβ
-
Find references to the old association and parameter:
grep -RInE '\bfiles\b|ct_bot_message\[files\]|with_attached_files' app config lib -
Change custom message creation and upload code from
filestoattachments, including permitted parameters, form fields, and model association calls. Usect_bot_message[attachments]for the request parameter andwith_attached_attachmentswhen eager-loading the association. -
Update any custom validations or error handling that refers to the old attachment association. Catalyst's built-in message size validation now reports errors on
attachments. -
After migrating in a non-production environment, verify that existing message attachments are still available through
CtBotMessage#attachmentsand that new uploads work.
Message roles are stored as stringsβ
This affects host-app code that treats CtBotMessage#role as an integer or depends on the old two-value role enum. Roles are now string values: user, assistant, system, and tool. The migration maps the old integer values 0 and 1 to user and assistant; other integer values are mapped to assistant by the migration.
Migration Stepsβ
-
Search for role comparisons, serialization, or code that assumes integer role values:
grep -RInE 'CtBotMessage|\.role|role:' app config lib -
Update host-app code to use the string role names and the corresponding enum predicates, such as
user?orassistant?, rather than comparing role values to integers. -
Review custom data or code that may have written role values other than the previous
userandassistantvalues. The migration maps any other integer role toassistant; confirm that this is acceptable before applying it.
Required Migrationβ
Add RubyLLM persistence to existing Catalyst AI installsβ
This is required for host apps that already installed Catalyst AI using the Bot Conversations generator. The new conversation lifecycle depends on RubyLLM persistence tables, additional conversation and message columns, and a backfill that associates existing conversations with the configured bot model. Do not rerun the Bot Conversations generator on an existing install.
The generated migration also drops ct_cost_trackings, changes ct_bot_messages.role to a string, and renames existing message attachment records from files to attachments.
Migration Stepsβ
-
Back up the database and confirm that the backup can be restored. If existing
ct_cost_trackingsrecords must be retained, export or archive them before continuing; the generated migration drops that table and does not migrate its records. -
Update the host app's Catalyst dependency to v9.3.0 using its normal dependency-management process.
-
Generate the persistence migrations:
rails generate cm_admin:add_ruby_llm_persistence -
Review the generated files in
db/migratebefore applying them. Confirm that the migrations are appropriate for the host app's database and that no RubyLLM persistence tables have already been created. In particular, review thect_cost_trackingstable removal and the role conversion before proceeding. -
Check the host app's
ct-bot-modelplatform setting, if set, and confirm that the intended model can be found in the RubyLLM model catalog for provideropenrouter. The migration attempts to refresh the catalog and usesopenai/gpt-5.6-solwhen that setting is absent; verify the resultingruby_llm_model_idvalues after migration rather than assuming every conversation was linked. -
Apply the migrations in a staging environment first:
rails db:migrate -
Verify that the RubyLLM tables exist, existing conversations and message attachments remain available, the converted role values are correct, and existing conversations have the intended RubyLLM model association. Confirm that the exported or archived cost data is accessible if you chose to preserve it.
-
After staging checks pass, apply the same reviewed migration files to production using the host app's normal deployment process. Follow the app's normal job and web-process restart procedure so all processes run the updated code.
The generated migration drops ct_cost_trackings. The migration has no automatic backfill for those records, and rolling back the schema does not restore the dropped data. Do not apply it until the required historical data has been preserved and the migration has been reviewed.
Configuration Changesβ
Register RubyLlmUsage instead of CtCostTrackingβ
This affects host apps that registered Catalyst AI models in config.included_models. Update the existing list in config/initializers/zcm_admin.rb: remove CtCostTracking and add RubyLlmUsage. Keep the other models already registered by the app, including any existing Catalyst AI conversation, message, and transcription models.
Migration Stepsβ
-
Open
config/initializers/zcm_admin.rband find theconfig.included_modelsassignment. -
Replace the
CtCostTrackingentry withRubyLlmUsage. For example, change the relevant entries as follows while retaining the rest of the host app's list:# BeforeCtBotConversation, CtBotMessage, CtBotTranscription, CtCostTracking# AfterCtBotConversation, CtBotMessage, CtBotTranscription, RubyLlmUsage -
Search the complete host app configuration for any other
CtCostTrackingregistration and remove or update those references. -
Boot the app and verify that the LLM Usages admin model loads after the migrations are applied.
Checklistβ
- Back up the database and decide whether to export or archive historical
ct_cost_trackingsrecords. - Search for and update references to
CtCostTracking, its associations, and its removed helper methods. - Search for and update Catalyst AI attachment usage from
filestoattachments. - Review host-app message role handling and any custom role values before conversion.
- Update the Catalyst dependency to v9.3.0 and register
RubyLlmUsageinconfig/initializers/zcm_admin.rbinstead ofCtCostTracking. - Run
rails generate cm_admin:add_ruby_llm_persistenceand review the generated migrations, including the table drop and model backfill. - Apply and verify the migrations in staging, then deploy the reviewed migrations and updated application code to production.