[BUG] rails generate ruby_llm:install migrations fails due to references to non-existent tables

[matiasmoya]

Basic checks

• I searched existing issues - this hasn't been reported
• I can reproduce this consistently
• This is a RubyLLM bug, not my application code

What's broken?

The rails generate ruby_llm:install generator creates migrations with foreign key references to tables that haven't been created yet, causing migration failures.

How to reproduce

1. Create a new rails app
2. bundle add ruby_llm
3. bundle install
4. rails db:create db:migrate
5. rails generate ruby_llm:install
6. rails db:migrate

Expected behavior

Migrations should run successfully, creating all necessary tables and relationships.

What actually happened

The generated migrations contain t.references calls that reference tables (like models) that are created in later migrations. The migration attempts to create foreign key constraints to tables that don't exist yet.

❯ rails db:migrate
== 20250912205042 CreateChats: migrating ======================================
-- create_table(:chats)
bin/rails aborted!
StandardError: An error has occurred, this and all later migrations canceled: (StandardError)

PG::UndefinedTable: ERROR:  relation "models" does not exist
/home/user/code/rubyllm-bug-repro/db/migrate/20250912205042_create_chats.rb:3:in 'CreateChats#change'

Caused by:
ActiveRecord::StatementInvalid: PG::UndefinedTable: ERROR:  relation "models" does not exist (ActiveRecord::StatementInvalid)
/home/user/code/rubyllm-bug-repro/db/migrate/20250912205042_create_chats.rb:3:in 'CreateChats#change'

Caused by:
PG::UndefinedTable: ERROR:  relation "models" does not exist (PG::UndefinedTable)
/home/user/code/rubyllm-bug-repro/db/migrate/20250912205042_create_chats.rb:3:in 'CreateChats#change'
Tasks: TOP => db:migrate
(See full trace by running task with --trace)

Workaround:

1. Remove the t.references lines from the initial table creation migrations
2. Create a separate migration after all tables are created to add the foreign key references:
   rails generate migration add_references_to_chats_tool_calls_and_messages

class AddReferencesToChatsToolCallsAndMessages < ActiveRecord::Migration[8.1]
  def change
    add_reference :chats, :model, foreign_key: true
    add_reference :tool_calls, :message, null: false, foreign_key: true
    add_reference :messages, :chat, null: false, foreign_key: true
    add_reference :messages, :model, foreign_key: true
    add_reference :messages, :tool_call, foreign_key: true
  end
end

Environment

• Ruby version: ruby 3.4.5
• RubyLLM version: 1.7.1
• OS: Linux
• postgres (PostgreSQL) 17.6

[gobijan]

I ran into this same issue and noticed the root problem seems to be a circular foreign key dependency between messages and tool_calls tables.

Looking at how LLM APIs handle tool calls, I think the relationships should be:

• Tool calls belong to the assistant message that invoked them (tool_calls.message_id → messages.id)
• Tool response messages need to identify which tool call they're answering

For that second relationship, would it make sense to store tool_call_id as a string in the messages table WITHOUT a foreign key constraint?

create_table :messages do |t|
# ... other fields ...
t.string :tool_call_id # Instead of: t.references :tool_call, foreign_key: true
end

My reasoning:

1. This breaks the circular FK dependency
2. When a tool response comes back from the API with role='tool', it includes the original tool_call_id string (like "call_xyz123") that we can store directly
3. We can still match tool responses to their tool calls via this string ID
4. The tool_calls table already has a unique index on the tool_call_id string column

Am I understanding the data model correctly? It seems like tool response messages need to reference which tool call they're responding to, but using the API's string
identifier rather than a database FK would avoid the circular dependency issue.

Would love to hear if others have thoughts on this approach or if I'm missing something about how the gem intends to model these relationships!

[crmne]

Hey @matiasmoya thanks for reporting this and for the PR! I merged this immediately.

This also highlights one issue I've been having developing these migrations: we need automated tests for them that programmatically create new rails apps with postgres and mysql (and not just sqlite as I was testing it), and test the migrations with and without options (chat:Chat, chat:LLM::Chat, etc.). Anyone wants to take that on?

Regarding the circular foreign key, it's true that it could create problems particularly with DB dump/restore, but it should be no problem in normal ActiveRecord operations, as I understand it, and I'm not a big fan of the potential overhead in DB operations. Are you guys more versed in the performance implications of it?