@spec create_database(conn(), String.t()) :: :ok | {:error, TypeDB.Error.t()}

Creates a database. See TypeDB.Database.create/2.

@spec create_database!(conn(), String.t()) :: :ok

Creates a database, raising on failure. See TypeDB.Database.create!/2.

@spec databases(conn()) :: {:ok, [String.t()]} | {:error, TypeDB.Error.t()}

Lists databases. See TypeDB.Database.list/1.

@spec databases!(conn()) :: [String.t()]

Lists databases, raising on failure. See TypeDB.Database.list!/1.

@spec delete_database(conn(), String.t()) :: :ok | {:error, TypeDB.Error.t()}

Deletes a database and all of its data. See TypeDB.Database.delete/2.

@spec delete_database!(conn(), String.t()) :: :ok

Deletes a database, raising on failure. See TypeDB.Database.delete!/2.

@spec health(conn()) :: :ok | {:error, TypeDB.Error.t()}

Returns :ok when the server is reachable. See TypeDB.Server.health/1.

@spec health!(conn()) :: :ok

Returns :ok when the server is reachable, raising otherwise. See TypeDB.Server.health!/1.

@spec query(conn(), String.t(), String.t(), keyword()) ::
  {:ok, TypeDB.Answer.t()} | {:error, TypeDB.Error.t()}

Runs a single query in a transaction of its own.

TypeDB opens the transaction, runs the query, then commits or closes it — one HTTP round trip in total, which makes this the cheapest way to run a standalone query.

Options

• :transaction_type — :read, :write or :schema. Defaults to :schema, the only type that accepts every kind of query.

  A :schema transaction takes TypeDB's exclusive, database-wide schema lock for the duration of the call. One-shot queries left on the default therefore serialise against each other, and against anything else holding that lock. Pass transaction_type: :read for reads and :write for data changes — both are concurrent — and leave the default to define and undefine. Narrowing also has the server reject an accidental write.

• :commit — whether to commit a write or schema query. Defaults to true. Read queries never commit.

• :given_rows — input rows for the query's given stage; see TypeDB.Transaction.query/3 for how to parameterise a query safely.

• plus all query and transaction options from TypeDB.Options, and :timeout.

Raises

Unlike the rest of this module, query/4 has two failure paths. Anything the server rejects comes back as {:error, %TypeDB.Error{}}; anything rejected before the request is built raises, because there is no request to fail:

• ArgumentError for an invalid :transaction_type — that is a literal in your source, not data.
• TypeDB.Error with kind :config for a :given_rows value the driver cannot encode, including a negative TypeDB.Duration.

Examples

TypeDB.query(conn, "social", "match $p isa person; select $p;",
  transaction_type: :read,
  answer_count_limit: 100
)

# Dry run: execute the write, then throw it away.
TypeDB.query(conn, "social", "insert $p isa person;", commit: false)

# Parameterised, and therefore safe against TypeQL injection.
TypeDB.query(conn, "social", """
  given $n: string;
  insert $p isa person, has name == $n;
""", given_rows: [%{"n" => user_supplied_name}])

@spec query!(conn(), String.t(), String.t(), keyword()) :: TypeDB.Answer.t()

Runs a single query, raising TypeDB.Error on failure.

@spec start_link(keyword()) :: GenServer.on_start()

Starts a connection. See TypeDB.Config for options.

@spec stop(conn() | pid(), term(), timeout()) :: :ok

Stops a connection, by registered name or pid.

@spec transaction(
  conn(),
  String.t(),
  TypeDB.Transaction.type(),
  (TypeDB.Transaction.t() -> result),
  keyword()
) :: result | {:error, TypeDB.Error.t()}
when result: term()

Runs fun inside a transaction, committing on success.

The transaction is committed when fun returns, rolled back when it returns {:error, _}, and rolled back before the exception propagates when it raises, throws or exits. :read transactions are closed rather than committed, since there is nothing to commit.

Returns whatever fun returned, except that a successful :write/:schema block whose commit fails returns {:error, %TypeDB.Error{}}.

Options

Transaction options from TypeDB.Options, plus :timeout.

Examples

TypeDB.transaction(conn, "social", :write, fn tx ->
  TypeDB.Transaction.query!(tx, "insert $p isa person, has name 'Alice';")
  TypeDB.Transaction.query!(tx, "insert $p isa person, has name 'Bob';")
  :ok
end)
#=> :ok

# Returning {:error, _} rolls back and returns that error unchanged.
TypeDB.transaction(conn, "social", :write, fn tx ->
  case TypeDB.Transaction.query(tx, "insert $p isa person;") do
    {:ok, _} -> {:error, :changed_my_mind}
    error -> error
  end
end)
#=> {:error, :changed_my_mind}

@spec version(conn()) :: {:ok, TypeDB.Server.version()} | {:error, TypeDB.Error.t()}

Returns the server distribution and version. See TypeDB.Server.version/1.

@spec version!(conn()) :: TypeDB.Server.version()

Returns the server distribution and version, raising on failure. See TypeDB.Server.version!/1.