feat(clients): add nim-allographer client with BaraDB driver support

- Pure Nim wire protocol client (async + sync, no C FFI)
- Query Builder: fluent API, SQL generator, execution, transactions
- Schema Builder: create/alter/drop tables, column operations
- Connection pool with aging and timeout handling
- ORM integration via compile-time DB_BARADB switch
- Tests: test_open, test_query
- Documentation: README.md, PLAN_BARADB.md

clients/nim-allographer/documents/surrealdb/schema_builder.md

@@ -0,0 +1,147 @@
+Example: Schema Builder for SurrealDB
+===
+> [!WARNING]
+> SurrealDB support is planned for v3. The current implementation is for reference only and may not work as expected in v2.
+
+[back](../../README.md)
+
+## index
+<!--ts-->
+* [Example: Schema Builder for SurrealDB](#example-schema-builder-for-surrealdb)
+   * [index](#index)
+   * [About SurrealDB](#about-surrealdb)
+   * [Create table](#create-table)
+   * [Alter Table](#alter-table)
+      * [add column](#add-column)
+      * [drop column](#drop-column)
+      * [drop table](#drop-table)
+
+<!-- Created by https://github.com/ekalinin/github-markdown-toc -->
+<!-- Added by: root, at: Mon Jul 17 07:46:33 UTC 2023 -->
+
+<!--te-->
+
+---
+
+## About SurrealDB
+[SurrealDB official docs](https://surrealdb.com/docs)  
+[SurrealDB Github](https://github.com/surrealdb/surrealdb)
+
+SurrealDB is a next-generation database built on Rust that can handle all type of data structures-relational, document, and graph-and can run in-memory, on a single node, or in a distributed environment.  
+It's response is JSON and allographer return as `JsonNode`.
+
+## Create table
+You can create `SCHEMAFULL` table for SurrealDB.
+
+[DEFINE TABLE](https://surrealdb.com/docs/surrealql/statements/define/table)  
+[DEFINE FIELD](https://surrealdb.com/docs/surrealql/statements/define/field)
+
+```nim
+import std/asyncdispatch
+import allographer/connection
+import allographer/schema_builder
+
+let surreal = dbOpen(SurrealDb, "test", "test", "user", "pass", "http://surreal", 8000, 5, 30, false, false).await
+
+surreal.create(
+  table("auth", [
+    Column.increments("index"),
+    Column.uuid("uuid"),
+    Column.string("name"),
+    Column.timestamps()
+  ]),
+  table("user", [
+    Column.increments("index"),
+    Column.string("name"),
+    Column.foreign("auth").reference("id").onTable("auth").onDelete(SET_NULL)
+  ])
+)
+```
+
+These query run.
+
+```sql
+DEFINE TABLE `auth` SCHEMAFULL;
+INSERT INTO `_autoincrement_sequences` {table: "auth", column: "index", max_index: 0};
+DEFINE EVENT `autoincrement_auth_index` ON TABLE `auth` WHEN $event = "CREATE" THEN {
+  LET $val = (SELECT `max_index` FROM `_autoincrement_sequences` WHERE `table` = "auth" AND `column` = "index" LIMIT 1)[0].max_index + 1;
+  UPDATE `auth` MERGE {index: $val} WHERE id = $after.id;
+  UPDATE `_autoincrement_sequences` MERGE {max_index: $val} WHERE `table` = "auth" AND `column` = "index";
+};
+DEFINE FIELD `index` ON TABLE `auth` TYPE int;
+DEFINE INDEX `auth_index_unique` ON TABLE `auth` COLUMNS `index` UNIQUE;
+DEFINE FIELD `uuid` ON TABLE `auth` TYPE string VALUE $value OR rand::uuid() ASSERT $value != NONE;
+DEFINE INDEX `auth_uuid_unique` ON TABLE `auth` COLUMNS `uuid` UNIQUE;
+DEFINE FIELD `name` ON TABLE `auth` TYPE string ASSERT string::len($value) < 255 AND $value != NONE VALUE $value OR '';
+DEFINE FIELD `created_at` ON TABLE `auth` TYPE datetime VALUE $value OR time::now();
+DEFINE INDEX `auth_created_at_index` ON TABLE `auth` COLUMNS `created_at`;
+DEFINE FIELD `updated_at` ON TABLE `auth` TYPE datetime VALUE time::now();
+DEFINE INDEX `auth_updated_at_index` ON TABLE `auth` COLUMNS `updated_at`;
+
+DEFINE TABLE `user` SCHEMAFULL;
+INSERT INTO `_autoincrement_sequences` {table: "user", column: "index", max_index: 0};
+DEFINE EVENT `autoincrement_user_index` ON TABLE `user` WHEN $event = "CREATE" THEN {
+  LET $val = (SELECT `max_index` FROM `_autoincrement_sequences` WHERE `table` = "user" AND `column` = "index" LIMIT 1)[0].max_index + 1;
+  UPDATE `user` MERGE {index: $val} WHERE id = $after.id;
+  UPDATE `_autoincrement_sequences` MERGE {max_index: $val} WHERE `table` = "user" AND `column` = "index";
+};
+DEFINE FIELD `index` ON TABLE `user` TYPE int;
+DEFINE INDEX `user_index_unique` ON TABLE `user` COLUMNS `index` UNIQUE;
+DEFINE FIELD `name` ON TABLE `user` TYPE string ASSERT string::len($value) < 255 AND $value != NONE VALUE $value OR '';
+DEFINE FIELD `auth` ON TABLE `user` TYPE record (`auth`) ASSERT $value != NONE;
+```
+
+
+## Alter Table
+### add column
+```nim
+surreal.alter(
+  table("auth", [
+    Column.increments("index").add(),
+    Column.string("name").add(),
+  ]),
+  table("user", [
+    Column.string("email").unique().default("").add(),
+    Column.foreign("auth").reference("id").onTable("auth").onDelete(SET_NULL).add()
+  ])
+)
+```
+
+```sql
+INSERT INTO `_autoincrement_sequences` {table: "auth", column: "index", max_index: 0};
+DEFINE EVENT `autoincrement_auth_index` ON TABLE `auth` WHEN $event = "CREATE" THEN {
+  LET $val = (SELECT `max_index` FROM `_autoincrement_sequences` WHERE `table` = "auth" AND `column` = "index" LIMIT 1)[0].max_index + 1;
+  UPDATE `auth` MERGE {index: $val} WHERE id = $after.id;
+  UPDATE `_autoincrement_sequences` MERGE {max_index: $val} WHERE `table` = "auth" AND `column` = "index";
+}
+DEFINE FIELD `index` ON TABLE `auth` TYPE int
+DEFINE INDEX `auth_index_unique` ON TABLE `auth` COLUMNS `index` UNIQUE
+DEFINE FIELD `name` ON TABLE `auth` TYPE string ASSERT string::len($value) < 255 AND $value != NONE VALUE $value OR ''
+DEFINE FIELD `email` ON TABLE `user` TYPE string ASSERT string::len($value) < 255 AND $value != NONE VALUE $value OR ''
+DEFINE INDEX `user_email_unique` ON TABLE `user` COLUMNS `email` UNIQUE
+DEFINE FIELD `auth` ON TABLE `user` TYPE record (`auth`) ASSERT $value != NONE
+```
+
+### drop column
+```nim
+surreal.alter(
+  table("user", [
+    Column.dropColumn("name")
+  ])
+)
+```
+
+```sql
+REMOVE FIELD `name` ON TABLE `user`
+```
+
+### drop table
+```nim
+surreal.drop(
+  table("user")
+)
+```
+
+```sql
+REMOVE TABLE `user`
+```