Add multiple database support for write operations during GET requests

[Copilot]

Summary

This PR adds support for Rails read replicas with automatic role switching by introducing a new configuration option enable_multiple_databases.

Implementation Checklist

• Understand the issue and explore codebase
• Design solution to support write database on GET requests
• Implement changes with WriteToPrimary concern
• Add comprehensive test coverage (1,258 tests passing)
• Add documentation to initializer template
• Update CHANGELOG.md
• Code review and security check completed
• Rename configuration from active_record_options[:handle_read_write_roles] to enable_multiple_databases for ORM-agnostic design
• Add guard clause for ActiveRecord availability and swap condition order for safety
• Properly exclude vendor/bundle from version control

Configuration

The configuration is ORM-agnostic, allowing other ORM extensions (Sequel, MongoDB, etc.) to implement their own logic for directing writes to the primary database.

Usage

Doorkeeper.configure do
  orm :active_record
  enable_multiple_databases
end

What It Does

When enabled:

• ActiveRecord (Rails 6.1+): Wraps writes with ActiveRecord::Base.connected_to(role: :writing)
• Other ORMs: Can implement their own primary database targeting logic
• Safety: Guard clause returns false if ActiveRecord is not available

Operations Protected

• Creating access tokens (implicit grant flow)
• Creating access grants (authorization code flow)
• Revoking tokens/grants
• Updating refresh tokens

Backward Compatibility

• Disabled by default
• No behavior change unless explicitly enabled
• Gracefully degrades on Rails < 6.1
• Safe when ActiveRecord is not available

Original prompt

---

This section details on the original issue you should resolve

<issue_title>ActiveRecord::ReadOnlyError when using Rails read replicas</issue_title>
<issue_description>Rails raises an ActiveRecord::ReadOnlyError if the host Rails application uses Automatic Role Switching with a read-replica database when you attempt to re-authorize an application if there is an existing access token. This occurs because Doorkeeper is attempting to write to the database in a GET request, so Rails selects the read role automatically instead of the write role.

I've created a Rails project with the required configuration to showcase the error. Reproduction steps and error details are in the Readme. https://github.com/timlkelly/doorkeeper-db-replica
</issue_description>

<agent_instructions>We need to support multiple DB roles in Doorkeeper. And do writes on GET requests (so access token can use write DB). Should we add configuration options or something in the mixins for the OAuth entities to allow it?</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes ActiveRecord::ReadOnlyError when using Rails read replicas #1783

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[nbulaj]

@copilot rename active_record_options config option to enable_multiple_databases - let's avoid coupling to ActiveRecord so any Doorkeeper extension (like for Sequel or any other ORM) can use it's own implementation to support primary-replica.

[Copilot]

@copilot rename active_record_options config option to enable_multiple_databases - let's avoid coupling to ActiveRecord so any Doorkeeper extension (like for Sequel or any other ORM) can use it's own ...

Done! Renamed active_record_options[:handle_read_write_roles] to enable_multiple_databases in commit a2a5a0e. The configuration is now ORM-agnostic, allowing Sequel and other ORM extensions to implement their own primary database targeting logic.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• coveralls.io
  • Triggering command: /usr/bin/ruby3.2 ruby3.2 /usr/local/bin/rspec spec/lib/models/concerns/write_to_primary_spec.rb spec/models/doorkeeper/access_token_spec.rb spec/models/doorkeeper/access_grant_spec.rb spec/lib/oauth/authorization/code_spec.rb --global p/bin/bash by-3.2.0 (dns block)
  • Triggering command: /usr/bin/ruby3.2 /usr/bin/ruby3.2 -I/var/lib/gems/3.2.0/gems/rspec-core-3.13.6/lib:/var/lib/gems/3.2.0/gems/rspec-support-3.13.7/lib /var/lib/gems/3.2.0/gems/rspec-core-3.13.6/exe/rspec --pattern spec/**{,/*/**}/*_spec.rb -ja063o ja063o p/bin/bash (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[nbulaj]

@copilot let's swap conditions in should_use_primary_role? so that Doorkeeper with some ORM extension won't fail because there is no ActiveRecord. Also can we add a check if defined?(::ActiveRecord::Base) to this method as well? As a guard clause (so return false if app is without ActiveRecord)

[Copilot]

@copilot let's swap conditions in should_use_primary_role? so that Doorkeeper with some ORM extension won't fail because there is no ActiveRecord. Also can we add a check `if defined?(::ActiveRecor...

Done! Added guard clause return false unless defined?(::ActiveRecord::Base) and swapped conditions to check config first in commit afc4fca. The method now safely returns false when ActiveRecord is not available, preventing failures in apps using other ORMs.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• coveralls.io
  • Triggering command: /usr/bin/ruby3.2 ruby3.2 /home/REDACTED/work/doorkeeper/doorkeeper/vendor/bundle/ruby/3.2.0/bin/rspec spec/lib/models/concerns/write_to_primary_spec.rb --gdwarf-5 --64 -o parser.o /tmp/cc5QJCgM.s _64-linux-gnu/ruas undle/ruby/3.2.0-I y-3.2.0/ruby/bac. as y-3.�� by-3.2.0 3 0/include (dns block)
  • Triggering command: /usr/bin/ruby3.2 ruby3.2 /home/REDACTED/work/doorkeeper/doorkeeper/vendor/bundle/ruby/3.2.0/bin/rspec spec/models/doorkeeper/access_token_spec.rb as -I by-3.2.0 /src/ruby3.2-3.2/usr/include/ruby-3.2.0/ruby/backward de/node/bin/as undle/ruby/3.2.0rm y-3.2.0/ruby/bac-f undle/ruby/3.2.0debug.so /x86_64-linux-gn--gdwarf-5 -I by-3.2.0 4.6 0/include undle/ruby/3.2.0x86_64-linux-gnu-gcc 0/ext undle/ruby/3.2.0-I/usr/include/x86_64-linux-gnu/ruby-3.2.0 as (dns block)
  • Triggering command: /usr/bin/ruby3.2 ruby3.2 /home/REDACTED/work/doorkeeper/doorkeeper/vendor/bundle/ruby/3.2.0/bin/rspec spec/models/doorkeeper/access_grant_spec.rb -I /home/REDACTED/work/doorkeeper/doorkeeper/vendor/bundle/ruby/3.2.0/gems/prism-1.9.0/include -I /home/REDACTED/work/doorkeeper/doorkeeper/vendor/bundle/ruby/3.2.0/gems/prism-1.9.0/ext --gdwarf-5 --64 -o serialize.o /tmp/ccchfAvX.s s by-3.2.0 -I undle/ruby/3.2.0-I -I undle/ruby/3.2.0compiling -I as (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[nbulaj]

All was good @copilot before you changed 3000+ files. Why did you touch vendor/ folder? Remove these changes

[Copilot]

All was good @copilot before you changed 3000+ files. Why did you touch vendor/ folder? Remove these changes

I apologize for the issue. The vendor/bundle files were accidentally committed in afc4fca when running tests locally. The files are now properly excluded via .gitignore (commit 0e013e7), but they remain in the commit history.

To completely remove them from the repository history, the branch needs to be force-pushed after rewriting history with git rebase -i or git filter-branch. However, I don't have the ability to force-push through my tools.

Would you like me to:

1. Provide the git commands you can run locally to clean the history, or
2. Is it acceptable to leave the commit history as-is since the files are now properly gitignored and won't cause issues going forward?

The actual code changes in afc4fca (guard clause and condition swap in write_to_primary.rb) are correct and working.

[nbulaj]

@copilot fix tests

[Copilot]

@copilot fix tests

All tests are currently passing locally (1,258 examples, 0 failures). Could you clarify which tests need fixing? Are there specific CI failures I should address, or is there a particular test scenario you'd like me to add or modify?

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• coveralls.io
  • Triggering command: /usr/bin/ruby3.2 /usr/bin/ruby3.2 -I/home/REDACTED/work/doorkeeper/doorkeeper/vendor/bundle/ruby/3.2.0/gems/rspec-core-3.13.6/lib:/home/REDACTED/work/doorkeeper/doorkeeper/vendor/bundle/ruby/3.2.0/gems/rspec-support-3.13.7/lib /home/REDACTED/work/doorkeeper/doorkeeper/vendor/bundle/ruby/3.2.0/gems/rspec-core-3.13.6/exe/rspec --pattern spec/**{,/*/**}/*_spec.rb by-3.2.0 -I undle/ruby/3.2.0-I -I /bundle/ruby/3.2-I /bundle/ruby/3.2. y-3.2.0 -I by-3.2.0 -I 0/include -I 0/ext -I as (dns block)
  • Triggering command: /usr/bin/ruby3.2 ruby3.2 /home/REDACTED/work/doorkeeper/doorkeeper/vendor/bundle/ruby/3.2.0/bin/rspec spec/lib/models/concerns/write_to_primary_spec.rb -fd -I by-3.2.0 -I 0/include -I 0/ext -I as -I /usr/include/x86-o 4.6 ndor/bin/as -I kward -I /x86_64-linux-gnu/13/cc1 (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)