README

Copy Markdown View Source
Dllb

Dllb

Elixir client for the dllb multi-model NoSQL database

Hex.pm Hex Docs

Dllb provides a high-level Elixir API for communicating with the dllb database over TCP. It manages a NimblePool-based connection pool, speaks the dllb line-based wire protocol, and exposes a query builder plus result parsing so your application can focus on data rather than sockets.

Features

  • Connection pooling -- NimblePool-managed TCP sockets with automatic reconnection on dead connections.
  • Wire protocol -- Line-based text over TCP; supports JSON, toon, and CSV response formats.
  • Query builder -- Composable functions for CREATE, SELECT, UPDATE, DELETE, RELATE, DEFINE TABLE/FIELD/INDEX statements.
  • Result structs -- Typed structs (Ok, Created, Deleted, Rows, Error) parsed from server responses.
  • Vector index support -- HNSW index definitions with configurable dimension and distance metric.
  • MetaAST bridge -- Serialization between Metastatic AST 3-tuples and dllb documents/edges, including bulk tree ingestion.
  • Schema bootstrap -- Declarative schema definitions executed through any query function.
  • OTP-ready -- Application supervision tree with opt-in pool startup via config :dllb, enabled: true.

Installation

Add dllb to your list of dependencies in mix.exs:

def deps do
  [
    {:dllb, "~> 0.1.0"}
  ]
end

Configuration

# config/config.exs
config :dllb,
  enabled: true,
  host: "127.0.0.1",
  port: 3009,
  pool_size: 5,
  outcome: :json,
  timeout: 30_000

Setting enabled: false (the default) starts the application without the connection pool, which is useful for compile-time or test environments where no dllb server is available.

Options

  • :host -- server hostname or IP (default "127.0.0.1")
  • :port -- server port (default 3009)
  • :pool_size -- number of persistent TCP connections (default 5)
  • :outcome -- response format: :json, :toon, or :csv (default :json)
  • :timeout -- connection and receive timeout in milliseconds (default 30_000)

Usage

Basic queries

{:ok, %Dllb.Result.Rows{count: 3, data: rows}} = Dllb.query("SELECT * FROM users")

result = Dllb.query!("SELECT * FROM users WHERE age > 25")

Query builder

Dllb.Query.create("user", %{name: "Alice", age: 30})
# => "CREATE user SET age = 30, name = 'Alice'"

Dllb.Query.select("user", where: "age > 25", order: "name ASC", limit: 10)
# => "SELECT * FROM user WHERE age > 25 ORDER BY name ASC LIMIT 10"

Dllb.Query.relate("user:a", "follows", "user:b", %{since: "2024"})
# => "RELATE user:a->follows->user:b SET since = '2024'"

Schema bootstrap

{:ok, :bootstrapped} = Dllb.Schema.bootstrap(&Dllb.query/1)

MetaAST ingestion

context = %{language: :elixir, file_path: "/app/lib/parser.ex"}
{:ok, %{nodes: 42, edges: 17}} = Dllb.MetaAST.ingest_tree(ast, context, &Dllb.query/1)

Modules

  • Dllb -- top-level query interface (query/1, query!/1)
  • Dllb.Connection -- raw TCP socket operations (connect, query, close, alive?)
  • Dllb.Pool -- NimblePool connection pool with dead-socket detection
  • Dllb.Protocol -- wire format encoding/decoding (line-based text over TCP)
  • Dllb.Query -- query string builder for all dllb statement types
  • Dllb.Result -- typed structs for parsed server responses
  • Dllb.Schema -- declarative schema bootstrap (DEFINE TABLE/FIELD/INDEX)
  • Dllb.MetaAST -- Metastatic AST serialization and bulk ingestion
  • Dllb.Error -- exception struct with typed error classification

Documentation

hexdocs.pm/dllb

Credits

Created as part of the Oeditus code quality tooling ecosystem.

License

MIT