surql-definition-macros 0.2.1

A Rust procedural macro for generating SurrealDB table and field definitions.
Documentation

surql-definition-macros

surql-definition-macros is a Rust procedural macro crate that simplifies the process of generating SurrealDB table and field definitions. The crate provides the SurQLDefinition derive macro, which automatically creates SurrealDB schema queries based on annotated Rust structs.

Table of Contents

  1. Features
  2. Installation
  3. Usage
  4. Examples
    1. Simple Usage
    2. Advanced Usage
  5. Validation
  6. License
  7. Links

Features

  • Automatically generates SurrealDB table and field definitions from Rust structs.
  • Supports flexible types, default values, assertions, and permissions.
  • Provides runtime and compile-time query validation options.

Installation

Add surql-definition-macros to your Cargo.toml:

[dependencies]
surql-definition-macros = "0.2.1"

Usage

To use surql-definition-macros, simply derive SurQLDefinition on your struct and optionally use the provided attributes for customization:

  • surql_table: Specifies the table name.
  • surql_field: Configures field properties like type, default value, and assertions.
  • surql_field_permissions: Sets field-level permissions.
  • surql_table_permissions: Sets table-level permissions.
  • surql_query: Defines a custom SurrealDB query.

Examples

Simple Usage

Here’s a basic example showcasing the use of SurQLDefinition to generate SurrealDB schema queries for a struct with various primitive types:

use surql_definition_macros::SurQLDefinition;

#[derive(SurQLDefinition)]
struct SimpleStruct {
    i32_val: i32,
    bool_val: bool,
    string_val: String,
}

assert_eq!(
    SimpleStruct::schema_query(),
    "DEFINE TABLE simple_struct; DEFINE FIELD i32_val ON simple_struct TYPE int; DEFINE FIELD bool_val ON simple_struct TYPE bool; DEFINE FIELD string_val ON simple_struct TYPE string;"
);

Advanced Usage

In this example, the ComplexStruct demonstrates more advanced features like flexible types, custom field types, and default values:

use surql_definition_macros::SurQLDefinition;

#[derive(SurQLDefinition)]
struct ComplexStruct {
    #[surql_field(TYPE = "float", DEFAULT = "3.14")]
    float_val: f64,

    #[surql_field(TYPE = "string", FLEXIBLE)]
    flexible_string: String,
}

assert_eq!(
    ComplexStruct::schema_query(),
    "DEFINE TABLE complex_struct; DEFINE FIELD float_val ON complex_struct TYPE float DEFAULT 3.14; DEFINE FIELD flexible_string ON complex_struct FLEXIBLE TYPE string;"
);

Validation

surql-definition-macros supports runtime and compile-time validation of generated queries using the runtime_query_validation and compile_query_validation features, respectively. These features rely on the surrealdb-core crate for query parsing.

To enable validation, update your Cargo.toml:

[dependencies]
surql-definition-macros = { version = "0.2.1", features = ["runtime_query_validation"] }

License

This project is licensed under the MIT License. See the LICENSE file for details.

Links