Dagex

Dagex provides tools to create directed, acyclic graphs for your business entities. It relies on the PostgreSQL ltree extension and Ecto.

See the module documentation for Dagex for usage examples.

Installation

1. Add dependency

If available in Hex, the package can be installed by adding dagex to your list of dependencies in mix.exs:

def deps do
  [
    {:dagex, "~> 3.0"}
  ]
end

2. Add Dagex functionality to your Ecto repository:

defmodule MyApp.Repo do
  use Ecto.Repo, otp_app: :my_app, adapter: Ecto.Adapters.Postgres
  use Dagex.Repo
end

3. Generate a migration to add the necessary database tables and functions

Run mix ecto.gen.migration add_dagex_to_project then edit the resulting migration file:

defmodule MyApp.Repo.Migrations.AddDagexToProject do
  use Ecto.Migration

  def up do
    Dagex.Migrations.up()
  end

  def down do
    Dagex.Migrations.down()
  end
end

and then migrate your database with mix ecto.migrate.

4. Set up ecto_ltree for your project

ecto_ltree is already included as a dependency with the above step, and activating the ltree extension happened in the Dagex migration above.

However there are additional steps that ecto_ltree requires:

1. Define a type module with the Postgrex.Ltree custom extensions e.g. in a new filed called lib/postgrex_types.ex

2. Configure the Repo to use the previously defined type module

5. Use migrations to create db tables for the business entities that participate in a DAG:

Run mix ecto.gen.migration add_organizations then edit the resulting migration file:

defmodule MyApp.Repo.Migrations.AddOrganizations do
  require Dagex.Migrations

  use Ecto.Migration

  def change do
    create table("organizations") do
      add :name, :string, null: false
      timestamps()
    end

    # Adds triggers to the "organizations" table to maintain the associated DAG as
    # records are added/removed.
    Dagex.Migrations.setup_node_type("organizations", "3.0.0")
  end
end

5. Create your Ecto-backed entity and add Dagex functionality:

N.B. You can use any column type that Postgresql can convert to text as the entity's primary key, however, if your primary key field is a string, you MUST NOT allow the value "*" as this is reserved internally for the supremum of the graph. You will see an Ecto.ConstraintError on the dagex_reserved_supremum_id constraint if you attempt to insert such a record.

defmodule MyApp.Organization do
  use Dagex
  use Ecto.Schema

  schema "organizations" do
    field :name, :string
  end
end

See the module documentation for Dagex for information on the functionality that is added to your module when calling use Dagex.