Class: ActiveRecord::Materialized::Configuration

Inherits:
Object
  • Object
show all
Defined in:
lib/activerecord/materialized/configuration.rb

Overview

Global, app-wide defaults, set via configure. Individual views can override most of these with the corresponding DSL macro.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Configuration

Returns a new instance of Configuration.



128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
 
# File 'lib/activerecord/materialized/configuration.rb', line 128

def initialize
  @metadata_table_name = "ar_materialized_view_metadata"
  @partition_table_name = "ar_materialized_view_partitions"
  @write_outbox_table_name = "ar_materialized_view_write_outbox"
  @source_watermark_table_name = "ar_materialized_view_source_watermarks"
  @default_max_staleness = nil
  @refresh_timeout = nil
  @atomic_swap_refresh = true
  @default_refresh_strategy = :async
  @default_refresh_debounce = 2
  # @refresh_dispatcher intentionally unset — lazily resolved from ActiveJob availability.
  @refresh_queue_name = :materialized_views
  @default_cold_read_strategy = :read_through
  @replica_lag = 0
  @view_load_paths = ["app/models"]
end

Instance Attribute Details

#atomic_swap_refresh ⇒ Boolean

Returns whether a full refresh swaps a freshly built table in atomically.

Returns:

  • (Boolean) —

    whether a full refresh swaps a freshly built table in atomically



27
28
29
 
# File 'lib/activerecord/materialized/configuration.rb', line 27

def atomic_swap_refresh
  @atomic_swap_refresh
end

#default_cold_read_strategy ⇒ Object

Cold-read behavior: :read_through (serve from source), :serve_stale (serve the cache as-is), or :raise.



87
88
89
 
# File 'lib/activerecord/materialized/configuration.rb', line 87

def default_cold_read_strategy
  @default_cold_read_strategy
end

#default_max_staleness ⇒ Numeric, ...

Returns default max_staleness.

Returns:

  • (Numeric, ActiveSupport::Duration, nil) —

    default max_staleness



21
22
23
 
# File 'lib/activerecord/materialized/configuration.rb', line 21

def default_max_staleness
  @default_max_staleness
end

#default_refresh_debounce ⇒ Numeric

Returns default debounce window (seconds) for coalescing async refreshes.

Returns:

  • (Numeric) —

    default debounce window (seconds) for coalescing async refreshes



33
34
35
 
# File 'lib/activerecord/materialized/configuration.rb', line 33

def default_refresh_debounce
  @default_refresh_debounce
end

#default_refresh_strategy ⇒ Symbol

Returns default refresh strategy: :async, :immediate, or :manual.

Returns:

  • (Symbol) —

    default refresh strategy: :async, :immediate, or :manual



30
31
32
 
# File 'lib/activerecord/materialized/configuration.rb', line 30

def default_refresh_strategy
  @default_refresh_strategy
end

#maintenance_role ⇒ Symbol?

Rails multi-database role that maintenance writes (refresh/reconcile/rebuild) run under, so they target the primary in a writer/replica topology. nil (default) yields on the current connection — no routing. Requires the host app to have declared the role via connects_to.

Returns:

  • (Symbol, nil) 


66
67
68
 
# File 'lib/activerecord/materialized/configuration.rb', line 66

def maintenance_role
  @maintenance_role
end

#max_tracked_partitions ⇒ Object 



112
113
114
 
# File 'lib/activerecord/materialized/configuration.rb', line 112

def max_tracked_partitions
  @max_tracked_partitions ||= 1_000
end

#metadata_table_name ⇒ String

Returns name of the metadata table (default "ar_materialized_view_metadata").

Returns:

  • (String) —

    name of the metadata table (default "ar_materialized_view_metadata")



9
10
11
 
# File 'lib/activerecord/materialized/configuration.rb', line 9

def metadata_table_name
  @metadata_table_name
end

#partition_table_name ⇒ String

Returns name of the per-partition freshness table.

Returns:

  • (String) —

    name of the per-partition freshness table



12
13
14
 
# File 'lib/activerecord/materialized/configuration.rb', line 12

def partition_table_name
  @partition_table_name
end

#reconcile_queue_name ⇒ Object 



57
58
59
 
# File 'lib/activerecord/materialized/configuration.rb', line 57

def reconcile_queue_name
  @reconcile_queue_name || refresh_queue_name
end

#refresh_dispatcher ⇒ Object 



44
45
46
 
# File 'lib/activerecord/materialized/configuration.rb', line 44

def refresh_dispatcher
  @refresh_dispatcher || (active_job_available? ? :active_job : :async)
end

#refresh_queue_name ⇒ Symbol

Returns ActiveJob queue name used when refresh_dispatcher is :active_job.

Returns:

  • (Symbol) —

    ActiveJob queue name used when refresh_dispatcher is :active_job



49
50
51
 
# File 'lib/activerecord/materialized/configuration.rb', line 49

def refresh_queue_name
  @refresh_queue_name
end

#refresh_timeout ⇒ Integer?

Returns optional per-refresh timeout in seconds.

Returns:

  • (Integer, nil) —

    optional per-refresh timeout in seconds



24
25
26
 
# File 'lib/activerecord/materialized/configuration.rb', line 24

def refresh_timeout
  @refresh_timeout
end

#replica_lag ⇒ Numeric, ActiveSupport::Duration

Replication lag budget folded into time-based staleness: a view read from a replica is effectively view staleness + replication lag stale, so this tightens the effective max_staleness (a view goes stale this much sooner) to keep replica reads within budget. Keep it well below your smallest max_staleness — a value at or above it drives the effective window to zero, making that view perpetually stale (reconciled every tick). Defaults to 0 (no adjustment); a static estimate of a dynamic quantity — see the distributed-deployment guide.

Returns:

  • (Numeric, ActiveSupport::Duration) 


83
84
85
 
# File 'lib/activerecord/materialized/configuration.rb', line 83

def replica_lag
  @replica_lag
end

#source_watermark_table_name ⇒ String

Returns name of the CDC source-watermark table (per-partition applied-watermark tracking).

Returns:

  • (String) —

    name of the CDC source-watermark table (per-partition applied-watermark tracking)



18
19
20
 
# File 'lib/activerecord/materialized/configuration.rb', line 18

def source_watermark_table_name
  @source_watermark_table_name
end

#verification_role ⇒ Symbol?

Rails multi-database role that DataVerifier reads run under, so the (expensive) drift verification can be offloaded to a replica — the verify-on-replica / repair-on-primary split. nil (default) yields on the current connection.

Returns:

  • (Symbol, nil) 


73
74
75
 
# File 'lib/activerecord/materialized/configuration.rb', line 73

def verification_role
  @verification_role
end

#view_load_paths ⇒ Array<String>

App-relative directories the Railtie eager-loads on boot (and on each dev reload) so every view class is loaded — and its depends_on commit callbacks installed — even under Zeitwerk's lazy loading (config.eager_load = false, i.e. development and test). Without this, a view whose constant nothing has referenced yet has no callbacks, so writes to its dependencies silently don't schedule maintenance until something first touches the class. Defaults to ["app/models"] (where view classes conventionally live); set to [] to disable, or list your own directories. Only existing directories that are Zeitwerk autoload roots are loaded — a path outside the autoloader (or a production app that already eager-loads) is a safe no-op.

Returns:

  • (Array<String>) 


126
127
128
 
# File 'lib/activerecord/materialized/configuration.rb', line 126

def view_load_paths
  @view_load_paths
end

#write_outbox_table_name ⇒ String

Returns name of the write-outbox table (the optional trigger/outbox change source).

Returns:

  • (String) —

    name of the write-outbox table (the optional trigger/outbox change source)



15
16
17
 
# File 'lib/activerecord/materialized/configuration.rb', line 15

def write_outbox_table_name
  @write_outbox_table_name
end

Instance Method Details

#active_job_available? ⇒ Boolean

Whether ActiveJob is loaded — the single source of truth for the dispatcher default and the module's dispatch/enqueue guards. Extracted (rather than an inline defined?) so it is testable regardless of whether the host app pulled in ActiveJob.

Returns:

  • (Boolean) 


150
151
152
 
# File 'lib/activerecord/materialized/configuration.rb', line 150

def active_job_available?
  !defined?(ActiveJob::Base).nil?
end

#default_change_source ⇒ Object 



101
102
103
 
# File 'lib/activerecord/materialized/configuration.rb', line 101

def default_change_source
  @default_change_source ||= ChangeSource::CALLBACKS
end

#default_change_source=(value) ⇒ Symbol

Default change source for views: :callbacks (install ActiveRecord commit callbacks on depends_on models) or :none (install no callbacks; drive maintenance through the public ingestion API from an external adapter). A view can override this with change_source. Lazily defaulted (like max_tracked_partitions) so it stays out of initialize.

Returns:

  • (Symbol) 


97
98
99
 
# File 'lib/activerecord/materialized/configuration.rb', line 97

def default_change_source=(value)
  @default_change_source = ChangeSource.cast(value)
end