mgclient

Kind	ffi-c
Capabilities	ffi
Categories	database ffi
Keywords	memgraph mgclient graph database bolt

Memgraph mgclient native bindings for Kit

Files

File	Description
`.editorconfig`	Editor formatting configuration
`.gitignore`	Git ignore rules for build artifacts and dependencies
`.tool-versions`	asdf tool versions (Zig, Kit)
`LICENSE`	MIT license file
`README.md`	This file
`c/kit_mgclient.c`	C FFI wrapper
`c/kit_mgclient.h`	C header for FFI wrapper
`examples/basic.kit`	Basic Memgraph usage example
`kit.toml`	Package manifest with metadata, native requirements, and tasks
`src/mgclient.kit`	kit-mgclient: Memgraph `mgclient` bindings for Kit
`tests/live.test.kit`	Opt-in live integration tests against a running Memgraph server
`tests/mgclient.test.kit`	Core tests for decoding and query helpers

Dependencies

No Kit package dependencies.

This package does require the native mgclient library and headers to be

installed locally.

Installation

kit add gitlab.com/kit-lang/packages/kit-mgclient.git

Install the native mgclient library first. Upstream currently documents source

builds rather than a packaged Homebrew formula:

https://github.com/memgraph/mgclient#building-and-installing-on-apple
https://github.com/memgraph/mgclient#building-and-installing-on-linux

On macOS, building into the Homebrew prefix works well:

brew install cmake openssl@3
git clone https://github.com/memgraph/mgclient
cd mgclient
cmake -S . -B build \
  -DOPENSSL_ROOT_DIR="$(brew --prefix openssl@3)" \
  -DCMAKE_PREFIX_PATH="$(brew --prefix openssl@3)" \
  -DCMAKE_INSTALL_PREFIX="$(brew --prefix)" \
  -DCMAKE_BUILD_TYPE=Release
cmake --build build
cmake --install build

If Kit still cannot find mgclient, export the include and library paths before

kit install, kit run, or kit build:

export C_INCLUDE_PATH="$(brew --prefix)/include${C_INCLUDE_PATH:+:$C_INCLUDE_PATH}"
export LIBRARY_PATH="$(brew --prefix)/lib${LIBRARY_PATH:+:$LIBRARY_PATH}"
export DYLD_LIBRARY_PATH="$(brew --prefix)/lib${DYLD_LIBRARY_PATH:+:$DYLD_LIBRARY_PATH}"

Usage

import Kit.Mgclient as Mgclient

main = fn =>
  match Mgclient.init
    | Ok _ ->
      match Mgclient.connect "127.0.0.1" 7687
        | Ok session ->
          match Mgclient.ping session
            | Ok _ -> println "Memgraph ping succeeded"
            | Err e -> println "Memgraph ping failed: ${Error.message e}"

          match Mgclient.with-transaction session (fn(tx) =>
            Mgclient.execute-with tx "RETURN $started AS started, $origin AS origin" [
              ("started", Mgclient.MgParamDateTime (Mgclient.MgDateTime {
                seconds: 10, 
                nanoseconds: 20, 
                tz-offset-minutes: 30
              })), 
              ("origin", Mgclient.MgParamPoint2D (Mgclient.MgPoint2D {
                srid: 4326, 
                x: 1.25, 
                y: 2.5
              }))
            ]
          )
            | Ok result ->
              println "Columns: ${show (Mgclient.columns result)}"
              match List.nth 0 (Mgclient.rows result)
                | Some row ->
                  match Mgclient.row-get-date-time "started" row
                    | Some started ->
                      println "started.seconds: ${show (Mgclient.date-time-seconds started)}"
                    | None ->
                      println "No started datetime in first row"

                  match Mgclient.row-get-point-2d "origin" row
                    | Some point ->
                      println "origin: (${show (Mgclient.point-2d-x point)}, ${show (Mgclient.point-2d-y point)})"
                    | None ->
                      println "No origin point in first row"
                | None ->
                  println "No rows returned"
            | Err e ->
              println "Query failed: ${Error.message e}"

          Mgclient.disconnect session
          Mgclient.finalize
        | Err e ->
          println "Connection failed: ${Error.message e}"
          Mgclient.finalize
    | Err e ->
      println "Initialization failed: ${Error.message e}"

main

Parameterized queries use MgParamValue variants such as:

[
  ("name", Mgclient.MgParamString "Alice"), 
  ("age", Mgclient.MgParamInt 30), 
  ("active", Mgclient.MgParamBool true), 
  ("tags", Mgclient.MgParamList [
    Mgclient.MgParamString "red", 
    Mgclient.MgParamString "blue"
  ])
]

Verified parameter variants on the current Memgraph 3.9.0 local test path include

scalars plus:

MgParamDate
MgParamLocalTime
MgParamDateTime
MgParamDateTimeZoneId
MgParamLocalDateTime
MgParamDuration
MgParamPoint2D
MgParamPoint3D

Development

Running Examples

Run examples with the interpreter:

kit run examples/basic.kit --allow=ffi,file

Compile examples to a native binary:

kit build examples/basic.kit -o /tmp/kit-mgclient-basic --allow=ffi,file --no-spinner
/tmp/kit-mgclient-basic

Running Tests

Run the default test suite:

kit test tests/

Run the opt-in live test suite against a running Memgraph server:

KIT_MGCLIENT_LIVE_TESTS=1 kit test tests/live.test.kit --allow=ffi,file

Running kit dev

Run the standard development workflow:

kit dev --no-spinner

Local Memgraph Tasks

For local testing with Podman on macOS, this package provides helper tasks:

kit task memgraph-up
kit task test-live
kit task memgraph-logs
kit task memgraph-down

memgraph-up starts a Memgraph container that exposes Bolt on localhost:7687.

It uses the standalone memgraph/memgraph:3.9.0 image.

Recommended local verification flow:

kit task memgraph-up
kit install
kit test tests/
kit task test-live
kit run examples/basic.kit --allow=ffi,file
kit build examples/basic.kit -o /tmp/kit-mgclient-basic --allow=ffi,file --no-spinner
/tmp/kit-mgclient-basic

Cleaning Build Artifacts

Remove generated files, caches, and build artifacts:

kit task clean

Note: Defined in kit.toml.

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/mgclient/, making it available

for import as Kit.Mgclient in other projects.

License

This package is released under the MIT License - see LICENSE for details.

mgclient is released under the

Apache License 2.0.

Exported Functions & Types

`MgclientError`

MgclientError type.

Variants

MgclientInitError {message}

MgclientConnectionError {message}

MgclientQueryError {message}

MgclientDecodeError {message}

`MgNode`

MgNode type.

Variants

MgNode {id, labels, properties}

`MgRelationship`

MgRelationship type.

Variants

MgRelationship {id, start-id, end-id, rel-type, properties}

`MgUnboundRelationship`

MgUnboundRelationship type.

Variants

MgUnboundRelationship {id, rel-type, properties}

`MgPathSegment`

MgPathSegment type.

Variants

MgPathSegment {reversed, relationship}

`MgPath`

MgPath type.

Variants

MgPath {nodes, relationships}

`MgDate`

MgDate type.

Variants

MgDate {days}

`MgTime`

MgTime type.

Variants

MgTime {nanoseconds, tz-offset-seconds}

`MgLocalTime`

MgLocalTime type.

Variants

MgLocalTime {nanoseconds}

`MgDateTime`

MgDateTime type.

Variants

MgDateTime {seconds, nanoseconds, tz-offset-minutes}

`MgDateTimeZoneId`

MgDateTimeZoneId type.

Variants

MgDateTimeZoneId {seconds, nanoseconds, timezone}

`MgLocalDateTime`

MgLocalDateTime type.

Variants

MgLocalDateTime {seconds, nanoseconds}

`MgDuration`

MgDuration type.

Variants

MgDuration {months, days, seconds, nanoseconds}

`MgPoint2D`

MgPoint2D type.

Variants

MgPoint2D {srid, x, y}

`MgPoint3D`

MgPoint3D type.

Variants

MgPoint3D {srid, x, y, z}

`MgValue`

MgValue type.

Variants

MgNull

MgBool {Bool}

MgInt {Int}

MgFloat {Float}

MgString {String}

MgList {_0}

MgMap {_0}

MgNodeValue {MgNode}

MgRelationshipValue {MgRelationship}

MgUnboundRelationshipValue {MgUnboundRelationship}

MgPathValue {MgPath}

MgDateValue {MgDate}

MgTimeValue {MgTime}

MgLocalTimeValue {MgLocalTime}

MgDateTimeValue {MgDateTime}

MgDateTimeZoneIdValue {MgDateTimeZoneId}

MgLocalDateTimeValue {MgLocalDateTime}

MgDurationValue {MgDuration}

MgPoint2DValue {MgPoint2D}

MgPoint3DValue {MgPoint3D}

`MgParamValue`

MgParamValue type.

Variants

MgParamNull

MgParamBool {Bool}

MgParamInt {Int}

MgParamFloat {Float}

MgParamString {String}

MgParamDate {MgDate}

MgParamLocalTime {MgLocalTime}

MgParamDateTime {MgDateTime}

MgParamDateTimeZoneId {MgDateTimeZoneId}

MgParamLocalDateTime {MgLocalDateTime}

MgParamDuration {MgDuration}

MgParamPoint2D {MgPoint2D}

MgParamPoint3D {MgPoint3D}

MgParamList {_0}

MgParamMap {_0}

`MgRow`

MgRow type.

Variants

MgRow {fields}

`MgResult`

MgResult type.

Variants

MgResult {columns, rows}

`decode-json-value`

decode json value.

See implementation.

`decode-json-result`

decode json result.

See implementation.

`columns`

columns.

See implementation.

`rows`

rows.

See implementation.

`column-count`

column count.

See implementation.

`row-count`

row count.

See implementation.

`first-row`

first row.

See implementation.

`has-result-column?`

has result column?.

See implementation.

`row-fields`

row fields.

See implementation.

`row-get`

row get.

See implementation.

`has-column?`

has column?.

See implementation.

`row-get-bool`

row get bool.

See implementation.

`row-get-int`

row get int.

See implementation.

`row-get-float`

row get float.

See implementation.

`row-get-string`

row get string.

See implementation.

`row-get-list`

row get list.

See implementation.

`row-get-map`

row get map.

See implementation.

`row-get-node`

row get node.

See implementation.

`row-get-relationship`

row get relationship.

See implementation.

`row-get-unbound-relationship`

row get unbound relationship.

See implementation.

`row-get-path`

row get path.

See implementation.

`row-get-date`

row get date.

See implementation.

`row-get-time`

row get time.

See implementation.

`row-get-local-time`

row get local time.

See implementation.

`row-get-date-time`

row get date time.

See implementation.

`row-get-date-time-zone-id`

row get date time zone id.

See implementation.

`row-get-local-date-time`

row get local date time.

See implementation.

`row-get-duration`

row get duration.

See implementation.

`row-get-point-2d`

row get point 2d.

See implementation.

`row-get-point-3d`

row get point 3d.

See implementation.

`node-id`

node id.

See implementation.

`node-labels`

node labels.

See implementation.

`node-properties`

node properties.

See implementation.

`node-has-label?`

node has label?.

See implementation.

`node-get`

node get.

See implementation.

`relationship-id`

relationship id.

See implementation.

`relationship-start-id`

relationship start id.

See implementation.

`relationship-end-id`

relationship end id.

See implementation.

`relationship-type`

relationship type.

See implementation.

`relationship-properties`

relationship properties.

See implementation.

`relationship-get`

relationship get.

See implementation.

`unbound-relationship-id`

unbound relationship id.

See implementation.

`unbound-relationship-type`

unbound relationship type.

See implementation.

`unbound-relationship-properties`

unbound relationship properties.

See implementation.

`unbound-relationship-get`

unbound relationship get.

See implementation.

`path-nodes`

path nodes.

See implementation.

`path-relationships`

path relationships.

See implementation.

`path-length`

path length.

See implementation.

`path-first-node`

path first node.

See implementation.

`path-last-node`

path last node.

See implementation.

`path-segment-reversed?`

path segment reversed?.

See implementation.

`path-segment-relationship`

path segment relationship.

See implementation.

`path-segment-type`

path segment type.

See implementation.

`path-segment-properties`

path segment properties.

See implementation.

`path-segment-get`

path segment get.

See implementation.

`path-segment-get-bool`

path segment get bool.

See implementation.

`path-segment-get-int`

path segment get int.

See implementation.

`path-segment-get-float`

path segment get float.

See implementation.

`path-segment-get-string`

path segment get string.

See implementation.

`date-days`

date days.

See implementation.

`time-nanoseconds`

time nanoseconds.

See implementation.

`time-tz-offset-seconds`

time tz offset seconds.

See implementation.

`local-time-nanoseconds`

local time nanoseconds.

See implementation.

`date-time-seconds`

date time seconds.

See implementation.

`date-time-nanoseconds`

date time nanoseconds.

See implementation.

`date-time-tz-offset-minutes`

date time tz offset minutes.

See implementation.

`date-time-zone-id-seconds`

date time zone id seconds.

See implementation.

`date-time-zone-id-nanoseconds`

date time zone id nanoseconds.

See implementation.

`date-time-zone-id-timezone`

date time zone id timezone.

See implementation.

`local-date-time-seconds`

local date time seconds.

See implementation.

`local-date-time-nanoseconds`

local date time nanoseconds.

See implementation.

`duration-months`

duration months.

See implementation.

`duration-days`

duration days.

See implementation.

`duration-seconds`

duration seconds.

See implementation.

`duration-nanoseconds`

duration nanoseconds.

See implementation.

`point-2d-srid`

point 2d srid.

See implementation.

`point-2d-x`

point 2d x.

See implementation.

`point-2d-y`

point 2d y.

See implementation.

`point-3d-srid`

point 3d srid.

See implementation.

`point-3d-x`

point 3d x.

See implementation.

`point-3d-y`

point 3d y.

See implementation.

`point-3d-z`

point 3d z.

See implementation.

`as-bool`

as bool.

See implementation.

`as-int`

as int.

See implementation.

`as-float`

as float.

See implementation.

`as-string`

as string.

See implementation.

`as-list`

as list.

See implementation.

`as-map`

as map.

See implementation.

`as-node`

as node.

See implementation.

`as-relationship`

as relationship.

See implementation.

`as-path`

as path.

See implementation.

`as-unbound-relationship`

as unbound relationship.

See implementation.

`as-date`

as date.

See implementation.

`as-time`

as time.

See implementation.

`as-local-time`

as local time.

See implementation.

`as-date-time`

as date time.

See implementation.

`as-date-time-zone-id`

as date time zone id.

See implementation.

`as-local-date-time`

as local date time.

See implementation.

`as-duration`

as duration.

See implementation.

`as-point-2d`

as point 2d.

See implementation.

`as-point-3d`

as point 3d.

See implementation.

`node-get-bool`

node get bool.

See implementation.

`node-get-int`

node get int.

See implementation.

`node-get-float`

node get float.

See implementation.

`node-get-string`

node get string.

See implementation.

`relationship-get-bool`

relationship get bool.

See implementation.

`relationship-get-int`

relationship get int.

See implementation.

`relationship-get-float`

relationship get float.

See implementation.

`relationship-get-string`

relationship get string.

See implementation.

`unbound-relationship-get-bool`

unbound relationship get bool.

See implementation.

`unbound-relationship-get-int`

unbound relationship get int.

See implementation.

`unbound-relationship-get-float`

unbound relationship get float.

See implementation.

`unbound-relationship-get-string`

unbound relationship get string.

See implementation.

`init`

init.

See implementation.

`finalize`

finalize.

See implementation.

`encode-param-value`

encode param value.

See implementation.

`encode-params`

encode params.

See implementation.

`connect`

connect.

See implementation.

`connect-auth`

connect auth.

See implementation.

`disconnect`

disconnect.

See implementation.

`is-connected?`

is connected?.

See implementation.

`ping`

ping.

See implementation.

`with-transaction-using`

with transaction using.

See implementation.

`begin`

begin.

See implementation.

`commit`

commit.

See implementation.

`rollback`

rollback.

See implementation.

`with-transaction`

with transaction.

See implementation.

`execute-json`

execute json.

See implementation.

`execute-json-with`

execute json with.

See implementation.

`execute`

execute.

See implementation.

`execute-with`

execute with.

See implementation.