ActiveRecord datasource

Connect Forest to your ActiveRecord models with support for relationships and Live Query

The ActiveRecord datasource enables importing collections from all model classes extending ActiveRecord::Base. It automatically respects your ActiveRecord relationships and configurations.

ActiveRecord datasource is only available for Ruby. For Node.js, check the Sequelize datasource or SQL datasource.

Basic usage

require 'forest_admin_datasource_active_record'

def self.setup!
  ForestAdminDatasourceActiveRecord::Datasource.new(
    {
      'adapter' => ENV['DB_ADAPTER'],
      'host' => ENV['DB_HOST'],
      'username' => ENV['DB_USERNAME'],
      'password' => ENV['DB_PASSWORD'],
      'database' => ENV['DB_DATABASE'],
    }
  )
end

Features

The ActiveRecord datasource automatically preserves your ORM configuration:

• ActiveRecord relationships - Relationships will be respected
• Live Query support - Users with proper permissions can create Live Query components for charts, analytics, and segments using SQL

Live Query support

Enable SQL-based reporting by setting a connection name identifier when creating the datasource:

ForestAdminDatasourceActiveRecord::Datasource.new(
  database_config,
  live_query_connections: 'main_database'
)

This allows authorized users to create Live Query charts, analytics, and segments that execute custom SQL directly against your database.

Live Queries execute raw SQL. Ensure proper access controls and review queries before deploying to production.

Multi-database configuration

For applications using multiple databases, provide a hash mapping display names to Rails connection identifiers:

ForestAdminDatasourceActiveRecord::Datasource.new(
  database_config,
  live_query_connections: {
    'main_database' => 'primary',
    'replica_database' => 'primary_replica'
  }
)

The configuration keys display in Forest’s UI, while the values reference connection names from your config/database.yml file.

Polymorphic relationships

Forest supports polymorphic relationships in ActiveRecord by enabling a specific configuration option on the datasource instance.

Configuration

To activate polymorphic relationship support, set the second parameter to true when instantiating the datasource:

def self.setup!
  database_configuration = Rails.configuration.database_configuration

  # Enable polymorphic relations with true parameter
  datasource = ForestAdminDatasourceActiveRecord::Datasource.new(
    database_configuration[Rails.env],
    true
  )

  @create_agent = ForestAdminAgent::Builder::AgentFactory.instance.add_datasource(datasource)
  customize
  @create_agent.build
end

Tips

The id and type fields of polymorphic relationships remain visible in the interface. Hide them through back-end customization or frontend configuration if desired.

Limitations

Collections

• Removal: Cannot delete collections that serve as polymorphic relationship targets; attempting this raises: “Cannot remove because it’s a potential target of polymorphic relation”
• Renaming: Cannot rename collections involved in polymorphic relationships; error states: “Cannot rename collection because it’s a target of a polymorphic relation”

Fields

• Removal: Cannot delete fields (foreign_key_type, foreign_key_id) used in polymorphic relationships
• Renaming: Cannot rename fields involved in these relationships
• Computed Fields: Cannot use polymorphic relationships as dependencies for computed fields due to unpredictable target collections

Search

Extended search functionality skips polymorphic relationships to prevent excessive resource consumption, generating debug logs about this behavior. Implement custom search behavior via documentation.

Source code

This connector is open source. Browse the code or contribute on GitHub: forest_admin_datasource_active_record.