An unofficial SurrealDB SDK for D

SurrealDB.D

D programming language bindings for SurrealDB -- based on the official C bindings.

⚠️ Work In Progress: This is an early development version of SurrealDB D bindings that i'm developing for my projects. While functional, the API may change significantly between versions. Use in production at your own risk.

Current Status

• Basic CRUD operations
• Query execution
• Connection management
• Complete test coverage
• Stable API
• High-level wrapper (planned)
• Documentation website
• CI/CD pipeline
• Package publication

Version: 0.1.0-alpha

Prerequisites

• D compiler ( Either DMD or LDC -- GDC has not yet been tested)
• DUB package manager
• Rust toolchain (for building SurrealDB)
• Cargo

Building

Run:

dub build

In the project's root directory. Dub will automatically build the SurrealDB Rust library during the D build process.

Example Usage

Note: API may change in future versions. Check the releases page for updates.

import std.stdio;
import surrealdb;

void main() {
    SrString err;
    SrSurreal* db;
    
    // Connect to database
    auto endpoint = "mem://\0".ptr;
    if (sr_connect(&err, &db, endpoint) < 0) {
        if (err.length > 0) {
            writefln("Connection error: %s", cast(string)err);
            sr_free_string(err);
        }
        return;
    }
    scope(exit) sr_surreal_disconnect(db);

    // Use namespace and database
    if (sr_use_ns(db, &err, "test\0".ptr) < 0) {
        writefln("Namespace error: %s", cast(string)err);
        sr_free_string(err);
        return;
    }

    if (sr_use_db(db, &err, "test\0".ptr) < 0) {
        writefln("Database error: %s", cast(string)err);
        sr_free_string(err);
        return;
    }

    // Create a record
    SrObject content = sr_object_new();
    scope(exit) sr_free_object(content);

    sr_object_insert_str(&content, "name\0".ptr, "John Doe\0".ptr);
    sr_object_insert_int(&content, "age\0".ptr, 30);
    sr_object_insert_str(&content, "email\0".ptr, "john@example.com\0".ptr);

    // Save the record
    SrObject* created;
    if (sr_create(db, &err, &created, "person\0".ptr, &content) < 0) {
        writefln("Create error: %s", cast(string)err);
        sr_free_string(err);
        return;
    }

    if (created !is null) {
        const(SrValue)* id = sr_object_get(created, "id\0".ptr);
        if (id !is null) {
            writeln("Created record with ID:");
            sr_value_print(id);
        }
        sr_free_object(*created);
    }
}

Running the Example

After building the library, run the following to see the example in action:

dub run -c example

Features

• Full SurrealDB API support
• Memory-safe bindings with scope-based cleanup
• Support for all SurrealDB data types
• Query execution and result handling
• Live query capabilities
• Transaction support
• Error handling

API Documentation

Connection Management

• sr_connect - Connect to a SurrealDB instance
• sr_surreal_disconnect - Disconnect from database
• sr_use_ns - Select a namespace
• sr_use_db - Select a database

Data Operations

• sr_create - Create a new record
• sr_query - Execute a SurrealQL query
• sr_select - Select records
• sr_select_live - Set up live query

Memory Management

• sr_free_string - Free string resources
• sr_free_object - Free object resources
• sr_free_arr - Free array resources
• sr_free_arr_res_arr - Free array result resources

Configurations

The package provides two configurations:

1. library (default) - Builds as a library for use in other projects
2. example - Builds and runs the example application

Project Structure

surrealdb/
├── source/
│   ├── app.d                 # Example application
│   ├── bindings/
│   │   └── surrealdb.d      # D bindings
│   └── surrealdb/           # Rust source
└── dub.json                 # Project configuration

License

Apache-2.0

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

As this project is in active development, we especially welcome:

• Bug reports
• Feature requests
• Documentation improvements
• Test cases
• API design suggestions

Please check the Issues page to see what's being worked on as it crops up, and feel free to submit a bug report if you find any issues.

Notes

• All strings passed to C functions must be null-terminated -- or you're gonna have a bad time.
• Memory management should use scope(exit) for cleanup
• Error handling should check both return values and error strings
• This is an early development version - API may change significantly