dumblepy · dumblepy · Mar 29, 2026 · Mar 28, 2026 · Mar 28, 2026 · Mar 29, 2026
diff --git a/documents/rdb/query_builder.md b/documents/rdb/query_builder.md
@@ -48,13 +48,20 @@ import allographer/connection
 
 let maxConnections = 95
 let timeout = 30
-let rdb = dbOpen(PostgreSQL, "database", "user", "password", "localhost", 5432, maxConnections, timeout)
 
-# also available
-# let rdb = dbOpen(Sqlite3, "/path/to/db/sqlite3.db", maxConnections=maxConnections, timeout=timeout)
-# let rdb = dbOpen(MySQL, "database", "user", "password", "localhost", 3306, maxConnections, timeout)
-# let rdb = dbOpen(MariaDB, "database", "user", "password", "localhost", 3306, maxConnections, timeout)
-# let rdb = dbOpen(PostgreSQL, databaseUrl = asDatabaseUrl("postgresql://user:password@localhost:5432/database"), maxConnections=maxConnections, timeout=timeout)
+# Using connection URL (Recommended)
+let rdb = dbOpen(PostgreSQL, "postgresql://user:password@localhost:5432/database", maxConnections, timeout)
+
+# Using positional arguments
+# let rdb = dbOpen(PostgreSQL, "database", "user", "password", "localhost", 5432, maxConnections, timeout)
+
+# SQLite
+# let rdb = dbOpen(SQLite3, "/path/to/db.sqlite3", maxConnections, timeout)
+# let rdb = dbOpen(SQLite3, ":memory:", maxConnections, timeout)
+
+# MySQL / MariaDB
+# let rdb = dbOpen(MySQL, "mysql://user:password@localhost:3306/database", maxConnections, timeout)
+# let rdb = dbOpen(MariaDB, "mariadb://user:password@localhost:3306/database", maxConnections, timeout)
 ```
 
 ## SELECT
@@ -294,7 +301,7 @@ let users = rdb
 
 ### paginate
 ```nim
-rdb.table("users").delete(2)
+rdb.table("users").delete(2).await
 let users = rdb
             .table("users")
             .select("id", "name")
@@ -486,7 +493,7 @@ rdb.table("users").insert(
 ```nim
 import allographer/query_builder
 
-rdb.table("users").inserts(
+echo rdb.table("users").insert(
   @[
     %*{"name": "John", "email": "John@gmail.com", "address": "London"},
     %*{"name": "Paul", "email": "Paul@gmail.com", "address": "London"},
@@ -531,7 +538,7 @@ echo rdb.table("users").insertId(
 ```nim
 import allographer/query_builder
 
-echo rdb.table("users").insertsID(
+echo rdb.table("users").insertId(
   @[
     %*{"name": "John", "email": "John@gmail.com", "address": "London"},
     %*{"name": "Paul", "email": "Paul@gmail.com", "address": "London"},
@@ -669,7 +676,7 @@ Except of `count`, these functions return `Option` type.
 ```nim
 import allographer/query_builder
 
-echo rdb.table("users").count()
+echo rdb.table("users").count().await
 >> 10       # int
 
 let response = await rdb.table("users").max("name").await

diff --git a/documents/rdb/schema_builder.md b/documents/rdb/schema_builder.md
@@ -4,24 +4,24 @@ Example: Schema Builder
 
 ## index
 <!--ts-->
-* [Example: Schema Builder](#example-schema-builder)
-   * [index](#index)
-   * [Create table](#create-table)
-   * [Alter Table](#alter-table)
-      * [add column](#add-column)
-      * [change column](#change-column)
-      * [drop column](#drop-column)
-      * [rename table](#rename-table)
-      * [drop table](#drop-table)
-   * [Migration history](#migration-history)
-      * [seeder template](#seeder-template)
-   * [integer](#integer)
-   * [float](#float)
-   * [char](#char)
-   * [date](#date)
-   * [others](#others)
-   * [options](#options)
-   * [Foreign Key Constraints](#foreign-key-constraints)
+- [Example: Schema Builder](#example-schema-builder)
+  - [index](#index)
+  - [Create table](#create-table)
+  - [Alter Table](#alter-table)
+    - [add column](#add-column)
+    - [change column](#change-column)
+    - [drop column](#drop-column)
+    - [rename table](#rename-table)
+    - [drop table](#drop-table)
+  - [Migration history](#migration-history)
+    - [seeder template](#seeder-template)
+  - [integer](#integer)
+  - [float](#float)
+  - [char](#char)
+  - [date](#date)
+  - [others](#others)
+  - [options](#options)
+  - [Foreign Key Constraints](#foreign-key-constraints)
 
 <!-- Created by https://github.com/ekalinin/github-markdown-toc -->
 <!-- Added by: root, at: Mon Jul 17 07:46:21 UTC 2023 -->
@@ -32,9 +32,9 @@ Example: Schema Builder
 ## Create table
 ```nim
 import allographer/schema_builder
-from ../database import rdb
+import connections # or define rdb here
 
-rdb.create([
+rdb.create(
   table("auth", [
     Column.increments("id"),
     Column.uuid("uuid"),
@@ -44,21 +44,20 @@ rdb.create([
   table("users", [
     Column.increments("id"),
     Column.string("name"),
-    Column.foreign("auth_id").reference("id").onTable("auth").onDelete(SET_NULL)
-    Column.strForeign("uuid").reference("uuid")..onDelete(SET_NULL)
+    Column.foreign("auth_id").reference("id").onTable("auth").onDelete(SET_NULL),
+    Column.strForeign("uuid").reference("uuid").onTable("auth").onDelete(SET_NULL)
   ])
-])
+)
 ```
 
 ## Alter Table
 ### add column
 ```nim
 rdb.alter(
   table("auth", [
-    Column.increments("id").add(),
-    Column.string("name").add(),
+    Column.string("email").add(),
   ]),
-  table("users",[
+  table("users", [
     Column.string("email").unique().default("").add(),
     Column.foreign("auth_id").reference("id").onTable("auth").onDelete(SET_NULL).add()
   ])
@@ -70,10 +69,10 @@ rdb.alter(
 ### change column
 ```nim
 rdb.alter(
-  table("users",
+  table("users", [
     Column.renameColumn("name", "new_name"),
-    Column.char("name", 20).unique().default("").cange()
-  )
+    Column.char("name", 20).unique().default("").change()
+  ])
 )
 ```
 - Create new table with new column definition
@@ -85,16 +84,16 @@ rdb.alter(
 ### drop column
 ```nim
 rdb.alter(
-  table("users",
+  table("users", [
     Column.dropColumn("name")
-  )
+  ])
 )
 ```
 
 ### rename table
 ```nim
 rdb.alter(
-  rename("users", "new_users")
+  table("users").renameTo("new_users")
 )
 ```
 `>> ALTER TABLE users RENAME TO new_users`
@@ -108,18 +107,17 @@ rdb.drop(
 `>> DROP TABLE users`
 
 ## Migration history
-allographer generate `_migrations` table in your database. It has migration history data which have hash key generated a query.
+allographer generate `_allographer_migrations` table in your database. It has migration history data which have hash key generated a query.
 
 
 ```nim
 # migrate.nim
-import json
+import std/asyncdispatch
+import std/json
 import allographer/schema_builder
-import allographer/query_builder
-
-let rdb = dbopen(SQLite3, "/path/to/db.sqlite")
+import connections
 
-rdb.schema(
+rdb.create(
   table("auth", [
     Column.increments("id"),
     Column.string("name")
@@ -151,7 +149,7 @@ seeder rdb, "users":
 ```sh
 # first time
 nim c -r migrate
->> run query and generate `_migrations` table
+>> run query and generate `_allographer_migrations` table
 # secound time
 nim c -r migrate
 >> nothing to do

diff --git a/documents/rdb/typeDifinition.md b/documents/rdb/typeDifinition.md
@@ -37,7 +37,9 @@
 |binary|BLOB|BLOB|BYTEA|JString
 |boolean|TINYINT|TINYINT|BOOLEAN|JBool
 |enumField|VARCHAR|ENUM|CHARACTER|JString
-|json|TEXT|JSON|JSON|JString
+|json|TEXT|JSON|JSON|JObject / JArray *1|
+
+*1: For SQLite, it returns `JString`. For other databases, it returns parsed `JsonNode` (`JObject` or `JArray`).
 |foreign|INTEGER|INT|INT|JInt
 |strForeign|VARCHAR|VARCHAR|VARCHAR|JString
 

diff --git a/documents/surrealdb/schema_builder.md b/documents/surrealdb/schema_builder.md
@@ -34,12 +34,13 @@ You can create `SCHEMAFULL` table for SurrealDB.
 [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", "htttp://surreal", 8000, 5, 30, false, false).waitFor()
+let surreal = dbOpen(SurrealDb, "test", "test", "user", "pass", "http://surreal", 8000, 5, 30, false, false).await
 
-surreal.create([
+surreal.create(
   table("auth", [
     Column.increments("index"),
     Column.uuid("uuid"),
@@ -49,9 +50,9 @@ surreal.create([
   table("user", [
     Column.increments("index"),
     Column.string("name"),
-    Column.foreign("auth").reference("id").on("auth").onDelete(SET_NULL)
+    Column.foreign("auth").reference("id").onTable("auth").onDelete(SET_NULL)
   ])
-])
+)
 ```
 
 These query run.
@@ -96,9 +97,9 @@ surreal.alter(
     Column.increments("index").add(),
     Column.string("name").add(),
   ]),
-  table("user",[
+  table("user", [
     Column.string("email").unique().default("").add(),
-    Column.foreign("auth").reference("id").on("auth").onDelete(SET_NULL).add()
+    Column.foreign("auth").reference("id").onTable("auth").onDelete(SET_NULL).add()
   ])
 )
 ```
@@ -121,9 +122,9 @@ DEFINE FIELD `auth` ON TABLE `user` TYPE record (`auth`) ASSERT $value != NONE
 ### drop column
 ```nim
 surreal.alter(
-  table("user",
+  table("user", [
     Column.dropColumn("name")
-  )
+  ])
 )
 ```
 
@@ -133,7 +134,7 @@ REMOVE FIELD `name` ON TABLE `user`
 
 ### drop table
 ```nim
-rdb.drop(
+surreal.drop(
   table("user")
 )
 ```

diff --git a/example/columnType.nim b/example/columnType.nim
@@ -1,43 +1,42 @@
-import json, asyncdispatch
-
+# nim c -r -d:reset example/columnType.nim
+import std/json
+import std/asyncdispatch
 import ../src/allographer/query_builder
 import ../src/allographer/schema_builder
 import ./connections
 
 asyncBlock:
-  rdb.schema([
+  rdb.create([
     table("auth",[
-      Column().increments("id"),
-      Column().string("auth")
+      Column.increments("id"),
+      Column.string("auth")
     ]),
     table("users",[
-      Column().increments("id"),
-      Column().string("name").nullable(),
-      Column().string("email").nullable(),
-      Column().string("password").nullable(),
-      Column().string("address").nullable(),
-      Column().date("birth_date").nullable(),
-      Column().foreign("auth_id").reference("id").on("auth").onDelete(SET_NULL)
+      Column.increments("id"),
+      Column.string("name").nullable(),
+      Column.string("email").nullable(),
+      Column.string("password").nullable(),
+      Column.string("address").nullable(),
+      Column.date("birth_date").nullable(),
+      Column.foreign("auth_id").reference("id").onTable("auth").onDelete(SET_NULL)
     ]),
     table("sample", [
-      Column().increments("id"),
-      Column().float("float"),
-      Column().string("string"),
-      Column().datetime("datetime"),
-      Column().string("null").nullable(),
-      Column().boolean("is_admin")
+      Column.increments("id"),
+      Column.float("float"),
+      Column.string("string"),
+      Column.datetime("datetime"),
+      Column.string("null").nullable(),
+      Column.boolean("is_admin")
     ])
   ])
 
-  echo repr await rdb.table("users").select("id", "name", "address")
+  echo await rdb.select("id", "name", "address").table("users")
       .limit(2)
       .get()
 
-  echo await rdb.table("users").select("id", "name", "address").first()
+  echo await rdb.select("id", "name", "address").table("users").first()
 
-  echo await rdb.table("users")
-      .select("id", "name", "address")
-      .find(3)
+  echo await rdb.select("id", "name", "address").table("users").find(3)
 
   await rdb.table("sample").insert(%*{
     "id": 1,
@@ -47,17 +46,13 @@ asyncBlock:
     "is_admin": true
   })
 
-  echo await rdb.table("sample")
-    .select("id", "float", "string", "datetime", "null", "is_admin")
-    .get()
+  echo await rdb.select("id", "float", "string", "datetime", "null", "is_admin").table("sample").get()
 
-  echo await rdb.table("sample")
-    .select("id", "float", "string", "datetime", "null", "is_admin")
-    .get()
+  echo await rdb.select("id", "float", "string", "datetime", "null", "is_admin").table("sample").get()
 
 
   var sql = "update users set name='John' where id = 1"
   await rdb.raw(sql).exec()
 
   sql = "select * from users where id = 1"
-  echo await rdb.raw(sql).getRaw()
+  echo await rdb.raw(sql).get()