lmdb

LMDB embedded key-value store bindings for Kit

Files

Dependencies

No Kit package dependencies.

System Requirements

LMDB must be installed on the system before building or running this package.

Installation

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

Usage

import Kit.LMDB as Lmdb

main = fn =>
  println ("LMDB version: " ++ Lmdb.version)

  match Lmdb.open "/tmp/my-database"
    | Err e -> println ("Error: " ++ e)
    | Ok db ->
      defer Lmdb.close db

      # Store values
      match Lmdb.put db "name" "Kit"
        | Err e -> println ("put failed: " ++ e)
        | Ok _ -> no-op

      Lmdb.put db "version" "0.1.0"
      Lmdb.put db "language" "functional"

      # Read values
      match Lmdb.get db "name"
        | Some val -> println ("name: " ++ val)
        | None -> println "name: not found"

      match Lmdb.get db "missing"
        | Some val -> println ("missing: " ++ val)
        | None -> println "missing: not found"

      # Check key existence
      if Lmdb.has-key? db "name" then
        println "'name' exists"

      # Count and list entries
      println ("Entries: " ++ (show (Lmdb.count db)))
      keys = Lmdb.list-keys db
      println ("Keys: " ++ (show keys))

      # Update and delete values
      Lmdb.put db "version" "0.2.0"
      Lmdb.delete db "language"

main

API Notes

open creates the database directory if it does not already exist and uses a 10 MB default map size. Use open-with-size when the database needs more room:

match Lmdb.open-with-size "/tmp/large-db" 1073741824
  | Ok db -> Lmdb.close db
  | Err e -> println ("Error: " ++ e)

The high-level API stores string keys and string values:

get currently uses an empty string from the native wrapper as the missing-value sentinel, so empty stored values also read back as None. Store a non-empty marker value if an empty value must be distinguishable from a missing key.

Development

Running Examples

Run examples with the interpreter:

kit run examples/basic.kit

Compile examples to a native binary:

kit build examples/basic.kit && ./basic

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

Running kit dev

Run the standard development workflow (format, check, test):

kit dev

This will:

1. Format and check source files in src/
2. Run tests in tests/ with coverage

Checking Parity

Run interpreter/compiler parity checks for the example programs:

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

The examples import Kit.LMDB, so run kit install after native wrapper changes to refresh the local package cache used by compiled examples.

Generating Documentation

Generate API documentation from doc comments:

kit doc

Note: Kit sources with doc comments (##) will generate HTML documents in docs/*.html

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/lmdb/, making it available for import as Kit.LMDB in other projects.

Native Wrapper Notes

The package is declared as kind = "ffi-c" and builds libkit_lmdb.dylib from c/kit_lmdb.c. The C wrapper hides LMDB's explicit transaction API behind simple operations that Kit can call through extern-c.

kit.toml excludes examples, tests, docs, and timestamped parity result files from package installation. The clean task removes generated coverage, docs, lock files, caches, native build products, and parity reports.

License

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

LMDB is released under the OpenLDAP Public License.

Exported Functions & Types

open

Open an LMDB database environment.

Creates the directory if it doesn't exist. Uses a default map size of 10 MB (sufficient for most use cases; increase for larger databases).

Parameters:

Returns:

NonEmptyString -> Result Ptr String

match open "/tmp/mydb"
  | Ok db ->
    # ... use database ...
    close db
  | Err e -> println "Error: ${e}"

open-with-size

Open an LMDB database with a custom map size.

Parameters:

Returns:

NonEmptyString -> PositiveInt -> Result Ptr String

# Open with 1 GB map size
match open-with-size "/tmp/largedb" 1073741824
  | Ok db ->
    # ... use database ...
    close db
  | Err e -> println "Error: ${e}"

close

Close the database and release resources.

Parameters:

Ptr -> Unit

close db

put

Store a key-value pair in the database.

If the key already exists, its value is overwritten.

Parameters:

Returns:

Ptr -> NonEmptyString -> String -> Result Unit String

match put db "user:1" "Alice"
  | Ok _ -> println "Stored!"
  | Err e -> println "Error: ${e}"

get

Get a value by key from the database.

Parameters:

Returns:

Ptr -> NonEmptyString -> Option String

match get db "user:1"
  | Some val -> println ("Found: " ++ val)
  | None -> println "Not found"

delete

Delete a key from the database.

Parameters:

Returns:

Ptr -> NonEmptyString -> Result Unit String

match delete db "user:1"
  | Ok _ -> println "Deleted!"
  | Err e -> println "Error: ${e}"

has-key?

Check if a key exists in the database.

Parameters:

Returns:

Ptr -> NonEmptyString -> Bool

if has-key? db "user:1" then
  println "Key exists"

list-keys

List all keys in the database.

Parameters:

Returns:

Ptr -> [String]

keys = list-keys db
List.map (fn(k) => println k) keys

count

Count the number of entries in the database.

Parameters:

Returns:

Ptr -> Int

println ("Entries: " ++ (show (count db)))

version

Get the LMDB library version as a string.

Returns:

String

println ("LMDB: " ++ version())