class

MongrelDB::Client

Inherits Reference < Object

Client is the MongrelDB HTTP client. Create one with Client.new and a base URL, then use its methods for health, table management, CRUD, query, SQL, schema, and maintenance.

A Client is safe for concurrent use by multiple fibers once configured -- each request builds its own HTTP::Client.

Constructors

new(url : String = DEFAULT_BASE_URL, token : String | Nil = nil, username : String | Nil = nil, password : String | Nil = nil, connect_timeout : Float64 = 30.0, read_timeout : Float64 = 60.0)

Create a new MongrelDB client.

url - daemon base URL (e.g. http://127.0.0.1:8453). Defaults to DEFAULT_BASE_URL when empty.
token - bearer token (--auth-token mode). Takes precedence over basic-auth credentials when set.
username / password - basic auth (--auth-users mode).
connect_timeout - seconds to wait for the connection to open.
read_timeout - seconds to wait for one block of the response body.

Class methods

flatten_cells(cells : Cells) : Array(JSON::Any)

Convert a column-id-to-value map to the server's flat [col_id, value, col_id, value, ...] array. Pair order is not significant -- each value is preceded by its own column id. Flatten a column-id-to-value map to the server's flat [col_id, value, ...] array in ascending column-id order. Stable ordering is required for idempotency keys: the server hashes the request payload, and unordered hash iteration would make two commits of the same cells look like a reuse mismatch.

to_any(value) : JSON::Any

Coerce a Crystal value into a JSON::Any for the request payload.

Accepts the native Crystal scalars and containers callers pass in (from Cells/Column values as well as ad-hoc query-parameter literals). Generic Array and Hash literals (e.g. ["a", "b"] typed as Array(String)) are coerced element-wise so callers do not have to widen them to Array(CellValue) themselves.

Instance methods

auth?

True when a bearer token or basic-auth username is configured.

base_url

The daemon base URL the client was configured with (no trailing slash).

begin_transaction

Begin a batch transaction. Operations are staged locally and committed atomically in a single /kit/txn request.

cancel_query(query_id : String) : Hash(String, JSON::Any)

Request cancellation of a running SQL query.

commit_txn(ops : Array, idempotency_key : String | Nil = nil) : Array(Hash(String, JSON::Any))

Commit a batch of staged operations atomically. Exposed for the Transaction type; prefer Transaction#commit.

compact

Compact (merge sorted runs) across all tables.

compact_table(name : String) : Hash(String, JSON::Any)

Compact a single table.

count(table : String) : Int64

Get the row count for a table.

create_table(name : String, columns : Array(Column), constraints : Hash, indexes : Array(Index)) : Int64

Create a table with constraints and full secondary-index definitions.

create_table(name : String, columns : Array(Column), constraints : Hash) : Int64

Create a table with a constraints block (uniques, foreign keys).

create_table(name : String, columns : Array(Column)) : Int64

Create a table with typed columns. Returns the assigned table id.

delete(table : String, row_id : Int64) : Nil

Delete a row by its internal row id.

delete_by_pk(table : String, pk : CellValue) : Nil

Delete a row by its primary-key value.

drop_table(name : String) : Nil

Drop a table by name.

earliest_retained_epoch

The oldest epoch still available for AS OF EPOCH queries.

get(path : String) : Response

Perform a GET request and return the Response, mapping HTTP errors to typed exceptions.

health

Check whether the daemon is reachable and healthy. Returns true on a successful /health request, false on any error.

history_retention

Inspect the durable MVCC history window. Returns both history_retention_epochs and earliest_retained_epoch.

history_retention_epochs

Current number of commit epochs the daemon will retain for time travel.

http_delete(path : String) : Response

Perform a DELETE request and return the Response. (Named http_delete to avoid clobbering the typed CRUD method delete(table, row_id) defined above.)

post(path : String, body = nil) : Response

Perform a POST request with a JSON body (Content-Type: application/json) and return the Response. A nil body sends an empty request.

put(table : String, cells : Cells, idempotency_key : String | Nil = nil) : Hash(String, JSON::Any)

Insert a row.

table - table name.
cells - column id -> value pairs (e.g. {1 => 1, 2 => "Alice"}). Flattened to the server's [col_id, value, ...] array before sending.
idempotency_key - when non-empty, makes the commit safe to retry.

put(path : String, body) : Response

query(table : String) : QueryBuilder

Start a fluent QueryBuilder against table.

query_status(query_id : String) : QueryStatus

Retained SQL status for durable recovery (GET /queries/{query_id}).

retrieve_text(table : String, embedding_column : Int32, text : String, k : Int32 | Nil = nil, deadline_ms : Int64 | Nil = nil, max_work : Int64 | Nil = nil) : Hash(String, JSON::Any)

Text → embed → ANN retrieve (POST /kit/retrieve_text, 0.64+).

schema

Get the full schema catalog (table name -> descriptor).

schema_for(table : String) : Hash(String, JSON::Any)

Get the descriptor for a single table.

search(table : String) : SearchBuilder

Start a hybrid SearchBuilder against table (POST /kit/search).

set_history_retention_epochs(epochs : Int) : Hash(String, JSON::Any)

Set the durable MVCC history window. Requires ADMIN permission when the daemon runs with catalog authentication. Returns the post-update window.

sql(sql : String) : Array(JSON::Any)

Execute a SQL statement via the /sql endpoint, requesting JSON output. The server returns a JSON array of row objects keyed by column name. For statements that yield no rows (DDL/DML), an empty array is returned.

table_names

List all table names in the database (empty array when none).

upsert(table : String, cells : Cells, update_cells : Cells | Nil = nil, idempotency_key : String | Nil = nil) : Hash(String, JSON::Any)

Upsert a row (insert or update on a primary-key conflict).

update_cells - values written on a primary-key conflict (nil means DO NOTHING).
idempotency_key - idempotency key for safe retries.