TerminusDB.Remote (terminusdb_ex v0.3.3)

Copy Markdown View Source

Remote collaboration API for TerminusDB.

Wraps the /api/clone, /api/fetch, /api/push, and /api/pull endpoints for working with remote TerminusDB repositories.

All functions require a TerminusDB.Config scoped to a database (except clone/3 which creates a new database).

Quick start

config =
  TerminusDB.Config.new(endpoint: "http://localhost:6363")

# Clone a remote database
{:ok, _} = TerminusDB.Remote.clone(config, "https://data.terminusdb.org/public/star-wars", "star-wars",
  label: "Star Wars", comment: "Star Wars dataset")

# Push current branch to remote
{:ok, _} = TerminusDB.Remote.push(config, "origin", "main",
  author: "admin", message: "push changes")

Summary

Types

remote_opt()

Functions

clone(config, remote_url, newid, opts \\ [])

Clones a remote repository into a new local database.

clone!(config, remote_url, newid, opts \\ [])

Clones a remote repository, or raises.

fetch(config, opts \\ [])

Fetches branches from a remote repository.

fetch!(config, opts \\ [])

Fetches from remote, or raises.

pull(config, remote, remote_branch, opts \\ [])

Pulls updates from a remote repository into the current branch.

pull!(config, remote, remote_branch, opts \\ [])

Pulls from remote, or raises.

push(config, remote, remote_branch, opts \\ [])

Pushes the current branch to a remote repository.

push!(config, remote, remote_branch, opts \\ [])

Pushes to remote, or raises.

Types

remote_opt()

@type remote_opt() ::
  {:organization, String.t()}
  | {:repo, String.t()}
  | {:label, String.t()}
  | {:comment, String.t()}
  | {:author, String.t()}
  | {:message, String.t()}
  | {:remote_branch, String.t()}
  | {:push_prefixes, boolean()}

Functions

clone(config, remote_url, newid, opts \\ [])

@spec clone(TerminusDB.Config.t(), String.t(), String.t(), [remote_opt()]) ::
  {:ok, map()} | {:error, TerminusDB.Error.t()}

Clones a remote repository into a new local database.

Options

  • :label — database label (defaults to newid).
  • :comment — database comment (defaults to "").
  • :organization — target organization (defaults to config.organization).

Examples

iex> config = TerminusDB.Config.new(
...>   endpoint: "http://localhost:6363",
...>   adapter: fn req -> {req, Req.Response.new(status: 200, body: %{"api:status" => "api:success"})} end
...> )
iex> {:ok, resp} = TerminusDB.Remote.clone(config, "https://data.terminusdb.org/public/star-wars", "star-wars", label: "Star Wars")
iex> resp["api:status"]
"api:success"

clone!(config, remote_url, newid, opts \\ [])

@spec clone!(TerminusDB.Config.t(), String.t(), String.t(), [remote_opt()]) :: map()

Clones a remote repository, or raises.

Examples

iex> config = TerminusDB.Config.new(
...>   endpoint: "http://localhost:6363",
...>   adapter: fn req -> {req, Req.Response.new(status: 200, body: %{"api:status" => "api:success"})} end
...> )
iex> TerminusDB.Remote.clone!(config, "https://data.terminusdb.org/public/star-wars", "star-wars")
%{"api:status" => "api:success"}

fetch(config, opts \\ [])

@spec fetch(TerminusDB.Config.t(), [remote_opt()]) ::
  {:ok, map()} | {:error, TerminusDB.Error.t()}

Fetches branches from a remote repository.

Options

  • :organization — overrides config.organization.
  • :repo — overrides config.repo.
  • :remote_id — remote repository ID (default "origin").

Examples

iex> config = TerminusDB.Config.new(
...>   endpoint: "http://localhost:6363",
...>   adapter: fn req -> {req, Req.Response.new(status: 200, body: %{"api:status" => "api:success", "api:head_has_changed" => true})} end
...> ) |> TerminusDB.Config.with_database("mydb")
iex> {:ok, resp} = TerminusDB.Remote.fetch(config)
iex> resp["api:head_has_changed"]
true

fetch!(config, opts \\ [])

@spec fetch!(TerminusDB.Config.t(), [remote_opt()]) :: map()

Fetches from remote, or raises.

Examples

iex> config = TerminusDB.Config.new(
...>   endpoint: "http://localhost:6363",
...>   adapter: fn req -> {req, Req.Response.new(status: 200, body: %{"api:status" => "api:success", "api:head_has_changed" => false})} end
...> ) |> TerminusDB.Config.with_database("mydb")
iex> TerminusDB.Remote.fetch!(config)
%{"api:head_has_changed" => false}

pull(config, remote, remote_branch, opts \\ [])

@spec pull(TerminusDB.Config.t(), String.t(), String.t(), [remote_opt()]) ::
  {:ok, map()} | {:error, TerminusDB.Error.t()}

Pulls updates from a remote repository into the current branch.

Options

Same as push/4.

Examples

iex> config = TerminusDB.Config.new(
...>   endpoint: "http://localhost:6363",
...>   adapter: fn req -> {req, Req.Response.new(status: 200, body: %{"api:status" => "api:success"})} end
...> ) |> TerminusDB.Config.with_database("mydb")
iex> {:ok, resp} = TerminusDB.Remote.pull(config, "origin", "main", author: "admin", message: "pull")
iex> resp["api:status"]
"api:success"

pull!(config, remote, remote_branch, opts \\ [])

@spec pull!(TerminusDB.Config.t(), String.t(), String.t(), [remote_opt()]) :: map()

Pulls from remote, or raises.

Examples

iex> config = TerminusDB.Config.new(
...>   endpoint: "http://localhost:6363",
...>   adapter: fn req -> {req, Req.Response.new(status: 200, body: %{"api:status" => "api:success"})} end
...> ) |> TerminusDB.Config.with_database("mydb")
iex> TerminusDB.Remote.pull!(config, "origin", "main")
%{"api:status" => "api:success"}

push(config, remote, remote_branch, opts \\ [])

@spec push(TerminusDB.Config.t(), String.t(), String.t(), [remote_opt()]) ::
  {:ok, map()} | {:error, TerminusDB.Error.t()}

Pushes the current branch to a remote repository.

Options

  • :remote — remote name (default "origin").
  • :remote_branch — remote branch name (default config.branch).
  • :author — commit author.
  • :message — commit message.
  • :organization — overrides config.organization.
  • :repo — overrides config.repo.
  • :push_prefixes — also push prefixes (default false).

Examples

iex> config = TerminusDB.Config.new(
...>   endpoint: "http://localhost:6363",
...>   adapter: fn req -> {req, Req.Response.new(status: 200, body: %{"api:status" => "api:success", "api:repo_head_updated" => true})} end
...> ) |> TerminusDB.Config.with_database("mydb")
iex> {:ok, resp} = TerminusDB.Remote.push(config, "origin", "main", author: "admin", message: "push")
iex> resp["api:repo_head_updated"]
true

push!(config, remote, remote_branch, opts \\ [])

@spec push!(TerminusDB.Config.t(), String.t(), String.t(), [remote_opt()]) :: map()

Pushes to remote, or raises.

Examples

iex> config = TerminusDB.Config.new(
...>   endpoint: "http://localhost:6363",
...>   adapter: fn req -> {req, Req.Response.new(status: 200, body: %{"api:status" => "api:success", "api:repo_head_updated" => true})} end
...> ) |> TerminusDB.Config.with_database("mydb")
iex> TerminusDB.Remote.push!(config, "origin", "main")
%{"api:repo_head_updated" => true}