Docs / Packages / mgclient

mgclient

Kindffi-c
Capabilitiesffi
Categoriesdatabase ffi
Keywordsmemgraph mgclient graph database bolt

Memgraph mgclient native bindings for Kit

Files

FileDescription
.editorconfigEditor formatting configuration
.gitignoreGit ignore rules for build artifacts and dependencies
.tool-versionsasdf tool versions (Zig, Kit)
LICENSEMIT license file
README.mdThis file
c/kit_mgclient.cC FFI wrapper around mgclient
c/kit_mgclient.hC header for the FFI wrapper
examples/auth.kitExample: authenticated Memgraph connection
examples/basic.kitBasic Memgraph query and typed result example
examples/transactions.kitExample: explicit transaction handling
kit.tomlPackage manifest with metadata, native requirements, and tasks
src/mgclient.kitkit-mgclient: Memgraph mgclient bindings for Kit
tests/live.test.kitOpt-in live integration tests against Memgraph
tests/mgclient.test.kitUnit tests for encoding, decoding, rows, and transactions

Dependencies

No Kit package dependencies.

This package requires the native mgclient library and headers. The package

uses Kit's FFI capability and links against mgclient.

Installation

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

Install the native mgclient library before running kit install, kit run,

or kit build. 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 cannot find mgclient, export the include and library paths:

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.make-date-time 10 20 30)), 
              ("origin", Mgclient.MgParamPoint2D (Mgclient.make-point-2d 4326 1.25 2.5))
            ]
          )
            | Ok result ->
              println "Columns: ${show (Mgclient.columns result)}"
              match Mgclient.first-row 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:

[
  ("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

Use the exported make-* constructors for record-backed values, such as

make-date-time, make-date-time-zone-id, make-duration, make-point-2d,

and make-point-3d.

Development

Running Examples

Run examples with the interpreter:

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

Compile examples to native binaries:

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

The examples try to connect to Memgraph on 127.0.0.1:7687. If no server is

running, they should fail cleanly with a connection error.

Running Tests

Run the default test suite:

kit test tests/

Run the default test suite with coverage:

kit test tests/ --coverage

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

Local Memgraph Tasks

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

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

memgraph-up starts memgraph/memgraph:3.9.0 and exposes Bolt on

localhost:7687.

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

Running kit dev

Run the standard development workflow:

kit dev --no-spinner

This will:

  1. Ensure the native library is current
  2. Format and check source files in src/
  3. Type-check examples in examples/
  4. Run tests in tests/ with coverage

Running Parity Checks

Run interpreter/compiler parity checks for examples:

kit parity --no-spinner --failures-only

This builds and executes each example, then compares interpreter and compiled

output.

Generating Documentation

Generate API documentation from doc comments:

kit doc src/mgclient.kit

Note: Kit sources with doc comments (##) generate HTML documentation.

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}

make-date

date constructor.

Int -> MgDate

make-time

time constructor.

Int -> Int -> MgTime

make-local-time

local time constructor.

Int -> MgLocalTime

make-date-time

date time constructor.

Int -> Int -> Int -> MgDateTime

make-date-time-zone-id

date time zone id constructor.

Int -> Int -> String -> MgDateTimeZoneId

make-local-date-time

local date time constructor.

Int -> Int -> MgLocalDateTime

make-duration

duration constructor.

Int -> Int -> Int -> Int -> MgDuration

make-point-2d

point 2d constructor.

Int -> Float -> Float -> MgPoint2D

make-point-3d

point 3d constructor.

Int -> Float -> Float -> Float -> MgPoint3D

make-init-error

make init error.

See implementation.

make-connection-error

make connection error.

See implementation.

make-query-error

make query error.

See implementation.

make-decode-error

make decode error.

See implementation.

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.