Mnesiac

https://hexdocs.pm/mnesiac
Admin
Mnesiac is an Elixir library that simplifies auto-clustering of Mnesia distributed databases, making...
Tokens:5,257
Snippets:73
Trust Score:9
Update:5 months ago
Show doc for...
Tokens:
Raw
### Development Setup

Source: https://hexdocs.pm/mnesiac/index.html

Clone the Mnesiac repository, checkout a new branch, and install dependencies using `asdf` and `mix` for local development.

```bash
git clone https://github.com/beardedeagle/mnesiac.git
git checkout -b MyFeature
asdf install
mix local.hex --force
mix local.rebar --force
mix deps.get --force
mix deps.compile --force
mix compile --force
```

--------------------------------

### Install ASDF and Dependencies

Source: https://hexdocs.pm/mnesiac/readme.html

Install language versions using ASDF and force updates for local Hex and Rebar, then get and compile dependencies.

```bash
asdf install
mix local.hex --force
mix local.rebar --force
mix deps.get --force
mix deps.compile --force
mix compile --force
```

--------------------------------

### start

Source: https://hexdocs.pm/mnesiac/Mnesiac.html

Starts Mnesia as a standalone node.

```APIDOC
## start()

### Description
Starts Mnesia as a standalone node.

### Method
N/A (Function call)

### Endpoint
N/A

### Parameters
None

### Request Example
```
mnesiac:start().
```

### Response
#### Success Response
- **ok** (boolean) - Indicates if Mnesia started successfully.
```

--------------------------------

### Example store_options() Output

Source: https://hexdocs.pm/mnesiac/Mnesiac.Store.html

This example shows a typical return value for the store_options() callback, which is a keyword list used to configure Mnesia table properties. Defining :record_name sets the Mnesia table name.

```iex
iex> store_options()
[attributes: [...], index: [:topic_id], disc_copies: [node()]]
```

--------------------------------

### init_store()

Source: https://hexdocs.pm/mnesiac/Mnesiac.Store.html

This callback is responsible for initializing a Mnesia table when Mnesiac starts and finds no existing data or data to copy.

```APIDOC
## init_store()

### Description
This function is called by mnesiac either when it has no existing data to use or copy and will initialise a table.

### Callback Signature
```elixir
@callback init_store() :: term()
```

### Default Implementation
```elixir
def init_store do
  :mnesia.create_table(Keyword.get(store_options(), :record_name, __MODULE__), store_options())
end
```
```

--------------------------------

### Minimal Mnesiac Store Example

Source: https://hexdocs.pm/mnesiac/readme.html

Defines a minimal Mnesiac store with record definition, types, and store options.

```elixir
defmodule MyApp.ExampleStore do
  @moduledoc """
  Provides the structure of ExampleStore records for a minimal example of Mnesiac.
  """
  use Mnesiac.Store
  import Record, only: [defrecord: 3]

  @doc """Record definition for ExampleStore example record."""
  defrecord(
    :example,
    __MODULE__,
    id: nil,
    topic_id: nil,
    event: nil
  )

  @typedoc """ExampleStore example record field type definitions."""
  @type example ::
          record(
            :example,
            id: String.t(),
            topic_id: String.t(),
            event: String.t()
          )

  @impl true
  def store_options,
    do: [
      record_name: :example,
      attributes: example() |> example() |> Keyword.keys(),
      index: [:topic_id],
      ram_copies: [node()]
    ]
end
```

--------------------------------

### Minimal Mnesiac Store Example

Source: https://hexdocs.pm/mnesiac/index.html

Define a minimal Mnesia table store using `Mnesiac.Store`. This includes record definition, type specifications, and required `store_options/0`.

```elixir
defmodule MyApp.ExampleStore do
  @moduledoc """
  Provides the structure of ExampleStore records for a minimal example of Mnesiac.
  """
  use Mnesiac.Store
  import Record, only: [defrecord: 3]

  @doc """
  Record definition for ExampleStore example record.
  """
  defrecord(
    :example,
    __MODULE__,
    id: nil,
    topic_id: nil,
    event: nil
  )

  @typedoc """
  ExampleStore example record field type definitions.
  """
  @type example ::
          record(
            :example,
            id: String.t(),
            topic_id: String.t(),
            event: String.t()
          )

  @impl true
  def store_options,
    do: [
      record_name: :example,
      attributes: example() |> example() |> Keyword.keys(),
      index: [:topic_id],
      ram_copies: [node()]
    ]
end
```

--------------------------------

### Mnesiac Supervisor with libcluster

Source: https://hexdocs.pm/mnesiac/index.html

Integrate Mnesiac into your supervision tree when using `libcluster` for cluster management. Ensure `libcluster` starts before Mnesiac.

```elixir
topology = Application.get_env(:libcluster, :topologies)
hosts = topology[:myapp][:config][:hosts]

children = [
  {Cluster.Supervisor, [topology, [name: MyApp.ClusterSupervisor]]},
  {Mnesiac.Supervisor, [hosts, [name: MyApp.MnesiacSupervisor]]},
  ...
]
```

--------------------------------

### init_tables

Source: https://hexdocs.pm/mnesiac/Mnesiac.StoreManager.html

Initializes the tables.

```APIDOC
## init_tables()

### Description
Initializes the tables.

### Function Signature
init_tables()
```

--------------------------------

### init_mnesia

Source: https://hexdocs.pm/mnesiac/Mnesiac.html

Initializes Mnesia with strict host checking.

```APIDOC
## init_mnesia(nodes)

### Description
Starts Mnesia with strict host checking enabled.

### Method
N/A (Function call)

### Endpoint
N/A

### Parameters
#### Path Parameters
- **nodes** (list) - Required - A list of nodes to initialize Mnesia with.

### Request Example
```
mnesiac:init_mnesia([node1@host1, node2@host2]).
```

### Response
#### Success Response
- **ok** (boolean) - Indicates if Mnesia was initialized successfully.
```

--------------------------------

### store_options()

Source: https://hexdocs.pm/mnesiac/Mnesiac.Store.html

This callback returns the Mnesia store's configuration as a keyword list, allowing for customization of table attributes, indexes, and replication.

```APIDOC
## store_options()

### Description
This function returns the store's configuration as a keyword list. For more information on the options supported here, see mnesia's documentation.

### Callback Signature
```elixir
@callback store_options() :: term()
```

### Examples
```elixir
iex> store_options()
[attributes: [...], index: [:topic_id], disc_copies: [node()]]
```

**Note**: Defining `:record_name` in `store_options()` will set the mnesia table name to the same.
```

--------------------------------

### Run Tests and Generate Coverage

Source: https://hexdocs.pm/mnesiac/index.html

Execute tests and generate HTML coverage reports using `mix coveralls.html`, with options to trace execution and show the slowest tests.

```bash
mix coveralls.html --trace --slowest 10 --no-start
```

--------------------------------

### Initialize Mnesia on New Node

Source: https://hexdocs.pm/mnesiac/index.html

When a new node joins an Erlang/Elixir cluster without a clustering library, run `Mnesiac.init_mnesia/1` on the new node to initialize and copy store contents.

```elixir
Mnesiac.init_mnesia/1
```

--------------------------------

### Default init_store() Implementation

Source: https://hexdocs.pm/mnesiac/Mnesiac.Store.html

This function is called by Mnesiac to initialize a table when no existing data is available or needs to be copied. It creates a new Mnesia table using the provided store options.

```elixir
def init_store do
  :mnesia.create_table(Keyword.get(store_options(), :record_name, __MODULE__), store_options())
end
```

--------------------------------

### create_tables

Source: https://hexdocs.pm/mnesiac/Mnesiac.StoreManager.html

Creates the necessary tables for the Mnesia store.

```APIDOC
## create_tables()

### Description
Creates the necessary tables for the Mnesia store.

### Function Signature
create_tables()
```

--------------------------------

### Clone Mnesiac Repository

Source: https://hexdocs.pm/mnesiac/readme.html

Clone the Mnesiac repository to set up the development environment.

```bash
git clone https://github.com/beardedeagle/mnesiac.git
git checkout -b MyFeature
```

--------------------------------

### Configure Mnesiac Stores

Source: https://hexdocs.pm/mnesiac/index.html

Configure Mnesiac by specifying the list of Mnesia stores, schema type, and table load timeout in `config.exs`.

```elixir
config :mnesiac,
  stores: [MyApp.ExampleStore, ...],
  schema_type: :disc_copies, # defaults to :ram_copies
  table_load_timeout: 600_000 # milliseconds, default is 600_000
```

--------------------------------

### Add Mnesiac Supervisor with libcluster

Source: https://hexdocs.pm/mnesiac/readme.html

Integrate Mnesiac.Supervisor into your supervision tree when using libcluster.

```elixir
  ...

    topology = Application.get_env(:libcluster, :topologies)
    hosts = topology[:myapp][:config][:hosts]

    children = [
      {Cluster.Supervisor, [topology, [name: MyApp.ClusterSupervisor]]},
      {Mnesiac.Supervisor, [hosts, [name: MyApp.MnesiacSupervisor]]},
      ...
    ]

  ...
```

--------------------------------

### connect

Source: https://hexdocs.pm/mnesiac/Mnesiac.html

Connects to a Mnesia cluster with a specified node.

```APIDOC
## connect(cluster_node)

### Description
Connects to a Mnesia cluster with a specified node.

### Method
N/A (Function call)

### Endpoint
N/A

### Parameters
#### Path Parameters
- **cluster_node** (node()) - Required - The node to connect to.

### Request Example
```
mnesiac:connect(node@hostname).
```

### Response
#### Success Response
- **ok** (boolean) - Indicates if the connection was successful.
```

--------------------------------

### Add Mnesiac Supervisor without libcluster

Source: https://hexdocs.pm/mnesiac/readme.html

Integrate Mnesiac.Supervisor into your supervision tree when not using libcluster.

```elixir
  ...

    children = [
      {
        Mnesiac.Supervisor,
        [
          [:"test01@127.0.0.1", :"test02@127.0.0.1"],
          [name: MyApp.MnesiacSupervisor]
        ]
      },
      ...
    ]

  ...
```

--------------------------------

### ensure_tables_loaded

Source: https://hexdocs.pm/mnesiac/Mnesiac.StoreManager.html

Ensures that all tables are loaded.

```APIDOC
## ensure_tables_loaded()

### Description
Ensures that all tables are loaded.

### Function Signature
ensure_tables_loaded()
```

--------------------------------

### copy_store()

Source: https://hexdocs.pm/mnesiac/Mnesiac.Store.html

This callback is invoked when Mnesiac joins a cluster and finds store data on a remote node. It handles copying data to the local node if necessary.

```APIDOC
## copy_store()

### Description
This function is called by mnesiac when it joins a mnesia cluster and data for this store is found on the remote node in the cluster that is being connected to.

### Callback Signature
```elixir
@callback copy_store() :: term()
```

### Default Implementation
```elixir
def copy_store do
  for type <- [:ram_copies, :disc_copies, :disc_only_copies] do
    value = Keyword.get(store_options(), type, [])

    if Enum.member?(value, node()) do
      :mnesia.add_table_copy(Keyword.get(store_options(), :record_name, __MODULE__), node(), type)
    end
  end
end
```
```

--------------------------------

### join_cluster

Source: https://hexdocs.pm/mnesiac/Mnesiac.html

Joins the current node to an existing Mnesia cluster.

```APIDOC
## join_cluster(cluster_node)

### Description
Joins the current node to an existing Mnesia cluster.

### Method
N/A (Function call)

### Endpoint
N/A

### Parameters
#### Path Parameters
- **cluster_node** (node()) - Required - The node of the cluster to join.

### Request Example
```
mnesiac:join_cluster(node@hostname).
```

### Response
#### Success Response
- **ok** (boolean) - Indicates if the node successfully joined the cluster.
```

--------------------------------

### Default copy_store() Implementation

Source: https://hexdocs.pm/mnesiac/Mnesiac.Store.html

This function is called when Mnesiac joins a cluster and data for the store exists on a remote node. It adds a table copy to the remote node if specified in store_options.

```elixir
def copy_store do
  for type <- [:ram_copies, :disc_copies, :disc_only_copies] do
    value = Keyword.get(store_options(), type, [])

    if Enum.member?(value, node()) do
      :mnesia.add_table_copy(Keyword.get(store_options(), :record_name, __MODULE__), node(), type)
    end
  end
end
```

--------------------------------

### Purge Mnesia Database

Source: https://hexdocs.pm/mnesiac/index.html

Clean up the Mnesia database before running tests by executing `mix purge.db`.

```bash
mix purge.db
```

--------------------------------

### Mnesiac Supervisor without libcluster

Source: https://hexdocs.pm/mnesiac/index.html

Add Mnesiac.Supervisor to your supervision tree when not using a clustering library. Manually provide the list of nodes.

```elixir
children = [
  {
    Mnesiac.Supervisor,
    [
      [:"test01@127.0.0.1", :"test02@127.0.0.1"],
      [name: MyApp.MnesiacSupervisor]
    ]
  },
  ...
]
```

--------------------------------

### Add Mnesiac Dependency

Source: https://hexdocs.pm/mnesiac/index.html

Add Mnesiac to your project's dependencies in `mix.exs` to include it in your build.

```elixir
def deps do
  [
    {:mnesiac, "~> 0.3"}
  ]
end
```

--------------------------------

### running_nodes

Source: https://hexdocs.pm/mnesiac/Mnesiac.html

Returns a list of all running Mnesia nodes.

```APIDOC
## running_nodes()

### Description
Returns a list of all running Mnesia nodes.

### Method
N/A (Function call)

### Endpoint
N/A

### Parameters
None

### Request Example
```
mnesiac:running_nodes().
```

### Response
#### Success Response
- **nodes** (list) - A list of running Mnesia nodes.
```

--------------------------------

### copy_tables

Source: https://hexdocs.pm/mnesiac/Mnesiac.StoreManager.html

Copies tables to a specified cluster node.

```APIDOC
## copy_tables(cluster_node)

### Description
Copies tables to a specified cluster node.

### Function Signature
copy_tables(cluster_node)

### Parameters
#### Path Parameters
- **cluster_node** (node()) - Required - The node to copy the tables to.
```

--------------------------------

### copy_schema

Source: https://hexdocs.pm/mnesiac/Mnesiac.StoreManager.html

Copies the schema to a specified cluster node.

```APIDOC
## copy_schema(cluster_node)

### Description
Copies the schema to a specified cluster node.

### Function Signature
copy_schema(cluster_node)

### Parameters
#### Path Parameters
- **cluster_node** (node()) - Required - The node to copy the schema to.
```

--------------------------------

### get_table_cookies

Source: https://hexdocs.pm/mnesiac/Mnesiac.StoreManager.html

Returns a map of tables and their cookies.

```APIDOC
## get_table_cookies(node)

### Description
This function returns a map of tables and their cookies.

### Function Signature
get_table_cookies(node \
 node())

### Parameters
#### Path Parameters
- **node** (node()) - Optional - The node to get table cookies from. Defaults to the current node.
```

--------------------------------

### running_db_node?

Source: https://hexdocs.pm/mnesiac/Mnesiac.html

Checks if a given node is a running Mnesia database node.

```APIDOC
## running_db_node?(cluster_node)

### Description
Checks if a given node is a running Mnesia database node.

### Method
N/A (Function call)

### Endpoint
N/A

### Parameters
#### Path Parameters
- **cluster_node** (node()) - Required - The node to check.

### Request Example
```
mnesiac:running_db_node?(node@hostname).
```

### Response
#### Success Response
- **is_running_db** (boolean) - True if the node is a running Mnesia DB node, false otherwise.
```

--------------------------------

### Default resolve_conflict(node) Implementation

Source: https://hexdocs.pm/mnesiac/Mnesiac.Store.html

This function is called when Mnesiac detects data for a table on both the local and remote nodes during cluster connection. The default implementation logs a message and does nothing, effectively aborting the data copy.

```elixir
def resolve_conflict(cluster_node) do
  table_name = Keyword.get(store_options(), :record_name, __MODULE__)
  Logger.info(fn -> "[mnesiac:#{node()}] #{inspect(table_name)}: data found on both sides, copy aborted." end)

  :ok
end
```

--------------------------------

### cluster_status

Source: https://hexdocs.pm/mnesiac/Mnesiac.html

Retrieves the current status of the Mnesia cluster.

```APIDOC
## cluster_status()

### Description
Retrieves the current status of the Mnesia cluster.

### Method
N/A (Function call)

### Endpoint
N/A

### Parameters
None

### Request Example
```
mnesiac:cluster_status().
```

### Response
#### Success Response
- **status** (any) - Description of the cluster status.
```

--------------------------------

### delete_schema

Source: https://hexdocs.pm/mnesiac/Mnesiac.StoreManager.html

Deletes the schema.

```APIDOC
## delete_schema()

### Description
Deletes the schema.

### Function Signature
delete_schema()
```

--------------------------------

### resolve_conflict(node)

Source: https://hexdocs.pm/mnesiac/Mnesiac.Store.html

This callback is triggered when Mnesiac detects data for a table on both the local and the remote node during a cluster connection. It provides a mechanism to handle such conflicts.

```APIDOC
## resolve_conflict(node)

### Description
This function is called by mnesiac when it has detected data for a table on both the local node and the remote node of the cluster it is connecting to.

### Callback Signature
```elixir
@callback resolve_conflict(node()) :: term()
```

### Default Implementation
```elixir
def resolve_conflict(cluster_node) do
  table_name = Keyword.get(store_options(), :record_name, __MODULE__)
  Logger.info(fn -> "[mnesiac:#{node()}] #{inspect(table_name)}: data found on both sides, copy aborted." end)

  :ok
end
```

**Note**: The default implementation for this function is to do nothing.
```

--------------------------------

### node_in_cluster?

Source: https://hexdocs.pm/mnesiac/Mnesiac.html

Checks if a given node is part of the Mnesia cluster.

```APIDOC
## node_in_cluster?(cluster_node)

### Description
Checks if a given node is part of the Mnesia cluster.

### Method
N/A (Function call)

### Endpoint
N/A

### Parameters
#### Path Parameters
- **cluster_node** (node()) - Required - The node to check.

### Request Example
```
mnesiac:node_in_cluster?(node@hostname).
```

### Response
#### Success Response
- **is_in_cluster** (boolean) - True if the node is in the cluster, false otherwise.
```

--------------------------------

### del_schema_copy

Source: https://hexdocs.pm/mnesiac/Mnesiac.StoreManager.html

Deletes a schema copy from a specified cluster node.

```APIDOC
## del_schema_copy(cluster_node)

### Description
Deletes a schema copy from a specified cluster node.

### Function Signature
del_schema_copy(cluster_node)

### Parameters
#### Path Parameters
- **cluster_node** (node()) - Required - The node from which to delete the schema copy.
```
Tokens:
Raw