Helper modules and your own tables

Small functions with no dependencies. The library uses get_unix_time/0 to fill the inserted_at and updated_at fields of its records.

Extra.erlang_fields({MyApp.Note}, [:id, :title, :tag], [:tag], 1)
# {MyApp.Note, :_, :_, :"$1"}

The library gives every plugin and installed library an id from generate/0.

Every function here must run inside a Transaction activity.

MishkaInstaller.MnesiaRepo creates one Mnesia table for each module in its :essential list when it boots. It calls database_config/0 of the module, gives the keyword list to Table.create_table/2, and names the table after the module. A module needs that one function. The example below stores notes with an index on tag, and uses the helpers above for the id, the time, the writes, the reads and a match specification. The Event and Installer tables of the library use UUID.generate/0 and Extra.get_unix_time/0 the same way, as the auto: generators of GuardedStruct fields.

Write the module

defmodule MyApp.Note do
  alias MishkaInstaller.Helper.{Extra, MnesiaAssistant, UUID}
  alias MishkaInstaller.Helper.MnesiaAssistant.{Query, Transaction}

  @fields [:id, :title, :tag, :inserted_at]

  defstruct @fields

  def database_config do
    [type: :set, attributes: @fields, index: [:tag], disc_copies: [node()]]
  end

  def write(title, tag) do
    note = %__MODULE__{
      id: UUID.generate(),
      title: title,
      tag: tag,
      inserted_at: Extra.get_unix_time()
    }

    record = List.to_tuple([__MODULE__ | Enum.map(@fields, &Map.fetch!(note, &1))])

    case Transaction.durable_transaction(fn -> Query.write(record) end) do
      {:atomic, :ok} ->
        {:ok, note}

      {:aborted, reason} ->
        Transaction.transaction_error(reason, __MODULE__, "storing", :global, :database)
    end
  end

  def get(id) do
    with {:ok, notes} <- read(fn -> Query.read(__MODULE__, id) end) do
      {:ok, List.first(notes)}
    end
  end

  def by_tag(tag), do: read(fn -> Query.index_read(__MODULE__, tag, :tag) end)

  def tags do
    head = MnesiaAssistant.erl_fields({__MODULE__}, @fields, [:tag], 1)
    spec = [{head, [], MnesiaAssistant.er(:selected)}]

    case Transaction.transaction(fn -> Query.select(__MODULE__, spec) end) do
      {:atomic, rows} ->
        {:ok, rows |> List.flatten() |> Enum.uniq() |> Enum.sort()}

      {:aborted, reason} ->
        Transaction.transaction_error(reason, __MODULE__, "reading", :global, :database)
    end
  end

  defp read(fun) do
    case Transaction.transaction(fun) do
      {:atomic, records} ->
        {:ok, MnesiaAssistant.tuple_to_map(records, @fields, __MODULE__, [])}

      {:aborted, reason} ->
        Transaction.transaction_error(reason, __MODULE__, "reading", :global, :database)
    end
  end
end

database_config/0 is the table. attributes names the fields in the order of the record tuple, index: [:tag] makes tag readable with index_read/3, and disc_copies: [node()] keeps the table in RAM and on the disc of the node that creates it. A record is the tuple {MyApp.Note, id, title, tag, inserted_at}: the table name, then the fields in the order of attributes. write/2 uses durable_transaction/1, so the record is on the disc when it returns. The reads use transaction/1.

List the module in :essential

Setting the key replaces the default list, so keep the two tables of the library. In a release, put this in config/runtime.exs:

config :mishka_installer, MishkaInstaller.MnesiaRepo,
  essential: [
    MishkaInstaller.Installer.Installer,
    MishkaInstaller.Event.Event,
    MyApp.Note
  ]

Check the boot

On the first boot the library creates the table and emits [:mishka_installer, :mnesia, :table] with table: MyApp.Note and status: :created. On every later boot the table exists, and the status is :already_loaded. See the telemetry documentation for the other statuses.

MyApp.Note in MishkaInstaller.MnesiaRepo.state().tables
# true

:mnesia.table_info(MyApp.Note, :storage_type)
# :disc_copies

Use the table

{:ok, note} = MyApp.Note.write("Write a plugin", "elixir")
{:ok, _} = MyApp.Note.write("Call an event", "elixir")
{:ok, _} = MyApp.Note.write("Deploy", "ops")

MyApp.Note.get(note.id)
# {:ok, %MyApp.Note{id: "f589696c-63e5-4bc2-a93f-b517e7edb135", title: "Write a plugin", tag: "elixir", inserted_at: 1792398438}}

MyApp.Note.by_tag("elixir")
# {:ok, [%MyApp.Note{title: "Write a plugin"}, %MyApp.Note{title: "Call an event"}]}, in no fixed order

MyApp.Note.tags()
# {:ok, ["elixir", "ops"]}

Stop the node and start it again: the notes are still there, because the table is on the disc.

What to know

• The module needs database_config/0. A module in :essential without it stops the boot. The library logs essential MyApp.Note exports no database_config/0, and the store does not start.
• The library creates a missing table and never changes an existing one. If you add a field to attributes later, the table on the disc keeps its old columns, and a write of the new record is refused. Change the table once with :mnesia.transform_table/3.
• A node that joins a cluster copies the tables in its own :essential list from the seed, as disc_copies. Give a joining node the same list as the seed. See the deploy to production documentation.
• In the test environment the library starts only its PubSub. Start MishkaInstaller.MnesiaRepo yourself, with a temporary mnesia_dir and the same :essential list. See the test your plugins documentation.

• Configuration reference: the :essential key and the other keys of the Mnesia store.
• Telemetry and log reference: the events and log messages of the Mnesia store.
• Event reference and Installer reference: the two tables the library keeps with these helpers.