RedisServerWrapper.Manager (redis_server_wrapper v0.7.4)

Copy Markdown View Source

Persistent instance manager for Redis server processes.

Tracks instances across IEx sessions via a JSON state file. Instances are detached by default so they outlive the Elixir process that started them.

Usage

Manager.start_basic(port: 6400)
Manager.start_cluster(masters: 3, base_port: 7100)
Manager.start_sentinel(master_port: 6390)

Manager.list()
Manager.info("redis-basic-1")
Manager.stop("redis-basic-1")
Manager.cleanup()

State is stored at ~/.config/redis-server-wrapper/instances.json. Mutating operations are serialized within a connected BEAM cluster and use atomic file replacement. Independent, unconnected BEAM instances must not write to the same state file concurrently.

Summary

Types

instance()
instance_type()

Functions

cleanup()

Removes instances from state that are no longer running.

credentials(name)

Returns the credentials for a named instance without printing them.

info(name)

Gets detailed info for a named instance, including live status.

list(type \\ nil)

Lists all tracked instances. Optionally filter by type: :basic, :cluster, :sentinel.

start_basic(opts \\ [])

Starts a basic single-node Redis instance.

start_cluster(opts \\ [])

Starts a Redis Cluster.

start_sentinel(opts \\ [])

Starts a Redis Sentinel topology.

stop(name)

Stops a named instance by sending SHUTDOWN to all its processes.

stop_all()

Stops all tracked instances.

Types

instance()

@type instance() :: %{
  name: String.t(),
  type: instance_type(),
  created_at: String.t(),
  bind: String.t(),
  ports: [non_neg_integer()],
  pids: [non_neg_integer()],
  username: String.t() | nil,
  password: String.t() | nil,
  connection: RedisServerWrapper.Connection.t(),
  url: String.t(),
  metadata: map()
}

instance_type()

@type instance_type() :: :basic | :cluster | :sentinel

Functions

cleanup()

@spec cleanup() :: {non_neg_integer(), non_neg_integer()}

Removes instances from state that are no longer running.

credentials(name)

@spec credentials(String.t()) ::
  {:ok,
   %{username: String.t() | nil, password: String.t() | nil, url: String.t()}}
  | {:error, :not_found}

Returns the credentials for a named instance without printing them.

Manager console output is redacted by default. Use this function when a caller explicitly needs the plaintext password or connection URL.

info(name)

@spec info(String.t()) :: {:ok, map()} | {:error, :not_found}

Gets detailed info for a named instance, including live status.

list(type \\ nil)

@spec list(instance_type() | nil) :: [instance()]

Lists all tracked instances. Optionally filter by type: :basic, :cluster, :sentinel.

start_basic(opts \\ [])

@spec start_basic(keyword()) :: {:ok, instance()} | {:error, term()}

Starts a basic single-node Redis instance.

Options

  • :name - instance name (auto-generated if omitted)
  • :port - Redis port (default: 6379)
  • :password - Redis password (auto-generated if omitted, pass nil for no auth)
  • :username - optional ACL username paired with :password
  • :bind - bind address (default: "127.0.0.1")
  • :control_host - address used for client and lifecycle operations
  • :persist - enable persistence (default: false)
  • :maxmemory - memory limit (e.g., "256mb")
  • :loadmodule - modules to load; accepts paths or {path, [args]} tuples
  • :distribution - :core (default), :full, or :legacy_stack
  • TCP, Unix-socket, and TLS options accepted by RedisServerWrapper.Server
  • Additional non-reserved Redis directives via :extra

start_cluster(opts \\ [])

@spec start_cluster(keyword()) :: {:ok, instance()} | {:error, term()}

Starts a Redis Cluster.

Options

  • :name - instance name (auto-generated if omitted)
  • :masters - number of masters (default: 3)
  • :replicas_per_master - replicas per master (default: 0)
  • :base_port - starting port (default: 7100)
  • :password - Redis password (auto-generated if omitted)
  • :username - optional ACL username paired with :password
  • :bind - bind address (default: "127.0.0.1")
  • :control_host - address used for client and cluster operations
  • :loadmodule - modules loaded into every cluster node
  • :distribution - :core (default), :full, or :legacy_stack
  • TLS options accepted by RedisServerWrapper.Cluster

start_sentinel(opts \\ [])

@spec start_sentinel(keyword()) :: {:ok, instance()} | {:error, term()}

Starts a Redis Sentinel topology.

Options

  • :name - instance name (auto-generated if omitted)
  • :master_port - master port (default: 6390)
  • :replicas - number of replicas (default: 2)
  • :sentinels - number of sentinels (default: 3)
  • :quorum - Sentinel quorum (default: min(2, sentinels))
  • :sentinel_base_port - starting sentinel port (default: 26389)
  • :password - Redis password (auto-generated if omitted)
  • :username - optional ACL username paired with :password
  • :bind - bind address (default: "127.0.0.1")
  • :loadmodule - modules loaded into the master and every replica
  • :distribution - :core (default), :full, or :legacy_stack
  • TLS options accepted by RedisServerWrapper.Sentinel

stop(name)

@spec stop(String.t()) :: :ok | {:error, term()}

Stops a named instance by sending SHUTDOWN to all its processes.

stop_all()

@spec stop_all() :: :ok | {:error, {:instances_not_stopped, map()}}

Stops all tracked instances.