Fact.DatabaseSupervisor (Fact v0.4.0)

Supervises all processes for a single Fact database instance.

Fact.DatabaseSupervisor is the top-level supervisor for a database, responsible for:

Registering the database in Fact.Registry
Supervising per-database registries and PubSub
Starting core database processes.
Starting indexers.

Each child process is registered under a database-specific name via Fact.Registry, ensuring isolation between multiple database instances.

This supervisor is automatically started by Fact.Supervisor when a database is initialized, and consumers typically interact with the database through higher-level APIs rather than directly starting this supervisor.

Summary

Types

indexer_spec()

Specifies a custom indexer to start with the database.

indexer_spec_option()

Options for an indexer_spec/0.

option()

Options used when starting a Fact.DatabaseSupervisor.

subsystem_option()

Options used when starting a Fact.DatabaseSupervisor.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

start_link(opts)

Starts a Fact.DatabaseSupervisor.

Types

indexer_spec()

(since 0.4.0)

@type indexer_spec() :: module() | {module(), [indexer_spec_option()]}

Specifies a custom indexer to start with the database.

Can be a bare module name or a {module, opts} tuple. When given as a bare module, the indexer is started with no key and no options.

Options

:key - An Fact.EventIndexer.indexer_key/0 for parameterized indexers. Allows multiple instances of the same module to run, each indexing a different dimension.
:options - A list of Fact.EventIndexer.indexer_option/0 values passed to the Fact.EventIndexer.index_event/3 callback.

Examples

# Bare module
MyApp.UserIndexer

# With a key (e.g. EventDataIndexer for a specific field)
{Fact.EventDataIndexer, key: "tenant_id"}

# With key and options
{MyApp.RegionIndexer, key: "us-east", options: [separator: "-"]}

indexer_spec_option()

(since 0.4.0)

@type indexer_spec_option() ::
  {:key, Fact.EventIndexer.indexer_key()}
  | {:options, Fact.EventIndexer.indexer_options()}

Options for an indexer_spec/0.

:key - An Fact.EventIndexer.indexer_key/0 to distinguish parameterized instances.
:options - Options forwarded to Fact.EventIndexer.index_event/3.

option()

(since 0.4.0)

@type option() :: {:context, Fact.Context.t()} | {:opts, [subsystem_option()]}

Options used when starting a Fact.DatabaseSupervisor.

:context - (required) The Fact.Context providing database identity and configuration.
:opts - (optional) Runtime options for database subsystems. See subsystem_option/0.

subsystem_option()

(since 0.3.1)

@type subsystem_option() ::
  {:cache, [Fact.RecordCache.cache_option()]}
  | {:indexers, indexer_spec()}
  | {:merkle, [Fact.MerkleMountainRange.merkle_option()]}
  | {:wal, [Fact.WriteAheadLog.wal_option()]}

Options used when starting a Fact.DatabaseSupervisor.

:context - (required) The Fact.Context providing database identity and configuration.
:opts - (optional) Runtime options for database subsystems. Supports:
- :cache - Record cache options. See Fact.RecordCache.cache_option/0.
- :indexers - Custom indexer specifications. See indexer_spec/0.
- :merkle - Merkle Mountain Range options. See Fact.MerkleMountainRange.merkle_option/0.
- :wal - Write-ahead log options. See Fact.WriteAheadLog.wal_option/0.

Functions

child_spec(init_arg)

(since 0.3.0)

@spec child_spec([option()]) :: Supervisor.child_spec()

Returns a specification to start this module under a supervisor.

The child spec is keyed by Fact.database_id/0, allowing multiple database instances to be supervised concurrently.

Requires the :context option to be specified. Optionally accepts :opts for database subsystem configuration. See subsystem_option/0.

start_link(opts)

(since 0.3.0)

@spec start_link([option()]) :: Supervisor.on_start()

Starts a Fact.DatabaseSupervisor.

This supervisor defines the runtime boundary for a single Fact database instance. It is registered under a database-scoped name via Fact.Registry, ensuring full isolation between multiple database instances running in the same VM.

At startup, this supervisor initializes all database-scope infrastructure, including registries, PubSub, core write coordination processes, and event indexers.

This function is typically invoked by Fact.Supervisor as part of database initialization and is not intended to be called directly by application code.