Bardo.Persistence (Bardo v0.1.0)

View Source

Core persistence module for Bardo.

This module provides a high-level API for saving and loading models, supporting both the default ETS-based storage and PostgreSQL storage for distributed environments.

It handles serialization, compression, migrations, and provides a consistent interface regardless of the underlying storage technology.

Summary

Functions

backup(path \\ "backups")

Create a backup of the database.

delete(type, id)

Delete a model from storage.

exists?(type, id)

Check if a model exists in storage.

export(model, file_path, opts \\ [])

Export a model to a file.

import(file_path, opts \\ [])

Import a model from a file.

list(type)

List all models of a given type.

load(type, id, opts \\ [])

Load a model from storage.

restore(backup_file)

Restore from a backup.

save(model, type, id \\ nil, opts \\ [])

Save a model to storage.

Functions

backup(path \\ "backups")

@spec backup(binary()) :: {:ok, binary()} | {:error, term()}

Create a backup of the database.

Parameters

  • path - Path to store the backup (default: "backups")

Returns

  • {:ok, backup_file} on success
  • {:error, reason} on failure

Examples

iex> Bardo.Persistence.backup("my_backups")
{:ok, "my_backups/bardo_backup_2025-05-07.db"}

delete(type, id)

@spec delete(atom(), binary()) :: :ok | {:error, term()}

Delete a model from storage.

Parameters

  • type - The type of model to delete (e.g., :experiment, :population, :genotype)
  • id - The ID of the model to delete

Returns

  • :ok on success
  • {:error, reason} on failure

Examples

iex> Bardo.Persistence.delete(:morphology, "morph_123")
:ok

exists?(type, id)

@spec exists?(atom(), binary()) :: boolean()

Check if a model exists in storage.

Parameters

  • type - The type of model to check (e.g., :experiment, :population, :genotype)
  • id - The ID of the model to check

Returns

  • true if the model exists
  • false if the model does not exist

Examples

iex> Bardo.Persistence.exists?(:morphology, "morph_123")
true

iex> Bardo.Persistence.exists?(:experiment, "nonexistent")
false

export(model, file_path, opts \\ [])

@spec export(map(), binary(), keyword()) :: :ok | {:error, term()}

Export a model to a file.

Parameters

  • model - The model to export
  • file_path - Path to save the file
  • opts - Additional options:
    • :format - Format to export in (:erlang, :json, or :etf, default: :erlang)
    • :compress - Whether to compress the file (default: false)

Returns

  • :ok on success
  • {:error, reason} on failure

Examples

iex> morphology = Bardo.Morphology.new(%{name: "Test"})
iex> Bardo.Persistence.export(morphology, "test_morphology.etf")
:ok

import(file_path, opts \\ [])

@spec import(
  binary(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Import a model from a file.

Parameters

  • file_path - Path to the file to import
  • opts - Additional options:
    • :format - Format of the file (:erlang, :json, or :etf, default: auto-detect)
    • :decompress - Whether to decompress the file (default: auto-detect)

Returns

  • {:ok, model} on success
  • {:error, reason} on failure

Examples

iex> Bardo.Persistence.import("test_morphology.etf")
{:ok, %{id: "morph_123", name: "Test", ...}}

list(type)

@spec list(atom()) :: {:ok, [map()]} | {:error, term()}

List all models of a given type.

Parameters

  • type - The type of models to list (e.g., :experiment, :population, :genotype)

Returns

  • {:ok, [model]} on success
  • {:error, reason} on failure

Examples

iex> Bardo.Persistence.list(:morphology)
{:ok, [%{id: "morph_123", name: "Test", ...}, ...]}

load(type, id, opts \\ [])

@spec load(atom(), binary(), keyword()) :: {:ok, map()} | {:error, term()}

Load a model from storage.

Parameters

  • type - The type of model to load (e.g., :experiment, :population, :genotype)
  • id - The ID of the model to load
  • opts - Additional options:
    • :decompress - Whether to decompress the model (default: auto-detect)
    • :format - Expected format (:erlang or :json, default: auto-detect)

Returns

  • {:ok, model} on success
  • {:error, reason} on failure

Examples

iex> Bardo.Persistence.load(:morphology, "morph_123")
{:ok, %{id: "morph_123", name: "Test", ...}}

iex> Bardo.Persistence.load(:experiment, "exp_123")
{:ok, %{id: "exp_123", data: %{name: "Test Experiment"}}}

restore(backup_file)

@spec restore(binary()) :: :ok | {:error, term()}

Restore from a backup.

Parameters

  • backup_file - Path to the backup file

Returns

  • :ok on success
  • {:error, reason} on failure

Examples

iex> Bardo.Persistence.restore("backups/bardo_backup_2025-05-07.db")
:ok

save(model, type, id \\ nil, opts \\ [])

@spec save(map(), atom(), binary() | nil, keyword()) :: :ok | {:error, term()}

Save a model to storage.

Parameters

  • model - The model to save
  • type - The type of model (e.g., :experiment, :population, :genotype)
  • id - Optional ID for the model (if not provided, extracted from the model)
  • opts - Additional options:
    • :compress - Whether to compress the model (default: false)
    • :format - Format to save in (:erlang or :json, default: :erlang)
    • :version - Schema version for future migrations

Returns

  • :ok on success
  • {:error, reason} on failure

Examples

iex> morphology = Bardo.Morphology.new(%{name: "Test"})
iex> Bardo.Persistence.save(morphology, :morphology)
:ok

iex> experiment = %{id: "exp_123", data: %{name: "Test Experiment"}}
iex> Bardo.Persistence.save(experiment, :experiment)
:ok