Sublimate is a helper library that builds database trigger logic for incremental updates to a destination table.

The data source can be a single source table or multiple joined tables. Changes to any of the source tables are staged to a deltas table. A merge function can then be applied - on demand or at scheduled intervals - to copy the changes to the destination table.

Sublimate maintains the destination table incrementally as the source changes; the consumer application/library defines what the destination contains and how staged changes merge into it.

One example of a consuming library is Refine ➚, which keeps a facets table up to date with changes in source tables.

Building blocks

Projection

The engine that builds and runs the infrastructure (deltas table, triggers) that keeps the destination table synchronized with its source tables, without knowing anything about the table's contents.

Projection-specific decisions are delegated to the projection's strategy (see below).

See: Sublimate.Projection

Strategy

The implementation of a specific projection. By implementing Sublimate.ProjectionStrategy callback functions, the consuming application/library instructs the projection how to keep the destination table synchronized.

See: Sublimate.ProjectionStrategy

Projection data

The attributes the projection operates on: the strategy module, and normalized and validated table and trigger references.

See: Sublimate.ProjectionData

Entry points

For a single projection, the lifecycle is:

• install/2 sets up a projection
• uninstall/2 or uninstall_all/2 tears down the projection
• merge/2 applies staged changes to the destination table

install/2 is composed of two lower-level functions, exposed for advanced use:

• create_shared_infrastructure/4 creates the deltas table and merge function
• install_triggers/3 installs a projection's source and joined-table triggers

Most consumers only need install/2. The two building blocks let a caller install several projections against one shared destination table - creating the shared infrastructure once, then installing each projection's triggers - which install/2, by recreating the deltas table and merge function on every call, cannot do.

See: Sublimate.Projection

Repo configuration

When calling Sublimate functions, the repo value in options can be omitted by passing otp_app in the projection_data parameter.

Sublimate reads the repo from the application's configuration under the :repo key:

config :my_app, repo: MyApp.Repo

Pass otp_app in the config given to ProjectionData.new/1, so Sublimate knows where to look:

config = %{
  source_table: "...",
  destination_table: "...",
  otp_app: :my_app,
  ...
}

If repo is given in the options, it is used directly; otherwise Sublimate falls back to the repo configured for otp_app.