# `Sublimate`

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 ➚](https://hex.pm/packages/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/3` sets up a projection
- `uninstall/3` tears it down
- `merge/3` applies staged changes to the destination table

To tear down several projections that share a destination, or to tear one down
without its config:

- `uninstall_projections/3` removes several projections, given their configs
- `uninstall_destination/3` removes a destination's maintenance (triggers, deltas
  table, merge function) discovered from the catalog, without needing the config.
  It does **not** drop the destination table itself.

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

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

Most consumers only need `install/3`. 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/3`,
by recreating the deltas table and merge function on every call, cannot do.

See: `Sublimate.Projection`

# `alias_column`

# `append_postgres_type`

# `distinct_table_names?`

# `fetch_table_columns`

# `fetch_table_columns!`

# `identity_column_exists?`

# `qualified_table_name`

# `run_queries`

# `run_query`

# `split_prefix_and_table_name`

# `table_alias`

# `table_exists?`

# `validate_identifier`

# `validate_postgrex_options`

# `wrap`

# `create_projection_data`

# `maybe_add_identity_column`

# `needs_identity_column?`

# `changed_table_anchor`

# `column_name_of`

# `column_ref_table`

# `create_shared_infrastructure`

# `emit_forward_joins`

# `emit_joins`

# `forward_joins_excluding_leaf`

# `install`

# `install_triggers`

# `joins_sql_without_leaf`

# `leaf_to_anchor`

# `merge`

# `same_table?`

# `source_nearest_anchor`

# `split_chain_at`

# `uninstall`

# `uninstall_destination`

# `uninstall_projections`

---

*Consult [api-reference.md](api-reference.md) for complete listing*