Merge branch 'main' into js-sdk-revamp

src/content/doc-sdk-rust/methods/connect.mdx

@@ -42,24 +42,23 @@ The `.connect()` method will usually take a `String` or a type that implements `
 where T: Into<String>`.
 
 ```rust
+use std::sync::LazyLock;
 use std::time::Duration;
 use surrealdb::engine::remote::ws::{Client, Ws, Wss};
 use surrealdb::opt::Config;
 use surrealdb::Surreal;
 
+static DB: LazyLock<Surreal<Client>> = LazyLock::new(Surreal::init);
+
 #[tokio::main]
 async fn main() -> surrealdb::Result<()> {
-    let db: Surreal<Client> = Surreal::init();
     // Connect to a local endpoint
-    db.connect::<Ws>("127.0.0.1:8000").await?;
+    DB.connect::<Ws>("127.0.0.1:8000").await?;
     // Connect to a remote endpoint
-    db.connect::<Wss>("cloud.surrealdb.com").await?;
+    DB.connect::<Wss>("cloud.surrealdb.com").await?;
     // A tuple with a Config struct can also be passed in for fine tuning of the connection
-    db.connect::<Ws>((
-        "127.0.0.1:8000",
-        Config::default().query_timeout(Duration::from_millis(1500)),
-    ))
-    .await?;
+    let config = Config::default().query_timeout(Duration::from_millis(1500));
+    DB.connect::<Ws>(("127.0.0.1:8000", config)).await?;
     Ok(())
 }
-```
+```

src/content/doc-sdk-rust/methods/create.mdx

@@ -46,6 +46,11 @@ db.create(resource).content(data)
 ### Example usage
 
 ```rust
+use serde::{Deserialize, Serialize};
+use surrealdb::engine::any::connect;
+use surrealdb::opt::auth::Root;
+use surrealdb::RecordId;
+
 #[derive(Debug, Serialize, Deserialize)]
 struct Person {
     name: Option<String>,
@@ -54,16 +59,17 @@ struct Person {
 
 #[derive(Debug, Deserialize)]
 struct Record {
-    id: Thing,
+    id: RecordId,
 }
 
-use serde::{Deserialize, Serialize};
-use surrealdb::engine::any::connect;
-use surrealdb::sql::Thing;
-
 #[tokio::main]
 async fn main() -> surrealdb::Result<()> {
     let db = connect("ws://localhost:8000").await?;
+    db.signin(Root {
+        username: "root",
+        password: "root",
+    })
+    .await?;
     db.use_ns("ns").use_db("db").await?;
 
     // Create a record with a random ID

src/content/doc-sdk-rust/methods/delete.mdx

@@ -36,28 +36,35 @@ db.delete(resource)
 ### Example usage
 
 ```rust
+use serde::{Deserialize, Serialize};
+use surrealdb::engine::any::connect;
+use surrealdb::opt::auth::Root;
+use surrealdb::opt::Resource;
+use surrealdb::RecordId;
+
 #[derive(Debug, Serialize, Deserialize)]
 struct Person {
-    id: Thing,
+    id: RecordId,
 }
 
-use serde::{Deserialize, Serialize};
-use surrealdb::engine::any::connect;
-use surrealdb::sql::Thing;
-
 #[tokio::main]
 async fn main() -> surrealdb::Result<()> {
     let db = connect("ws://localhost:8000").await?;
+    db.signin(Root {
+        username: "root",
+        password: "root",
+    })
+    .await?;
     db.use_ns("ns").use_db("db").await?;
 
     // Create three `person` records
-    let _: Option<Person> = db.create(("person", "one")).await?;
-    let _: Option<Person> = db.create(("person", "two")).await?;
-    let _: Option<Person> = db.create(("person", "three")).await?;
+    db.create(Resource::from(("person", "one"))).await?;
+    db.create(Resource::from(("person", "two"))).await?;
+    db.create(Resource::from(("person", "three"))).await?;
 
     let deleted_one: Option<Person> = db.delete(("person", "one")).await?;
-    let deleted_rest: Vec<Person> = db.delete("person").await?;
     dbg!(deleted_one);
+    let deleted_rest: Vec<Person> = db.delete("person").await?;
     dbg!(deleted_rest);
     Ok(())
 }

src/content/doc-sdk-rust/methods/export.mdx

@@ -42,49 +42,48 @@ db.export(target)
 The `.export()` method can be used to save the contents of a database to a file.
 
 ```rust
-#[derive(Debug, Serialize, Deserialize)]
-struct Person {
-    id: Thing,
-}
-
-use serde::{Deserialize, Serialize};
 use surrealdb::engine::any::connect;
-use surrealdb::sql::Thing;
+use surrealdb::opt::auth::Root;
+use surrealdb::opt::Resource;
 
 #[tokio::main]
 async fn main() -> surrealdb::Result<()> {
     let db = connect("http://localhost:8000").await?;
+    db.signin(Root {
+        username: "root",
+        password: "root",
+    })
+    .await?;
     db.use_ns("ns").use_db("db").await?;
 
     // Create a `person` record
-    let _: Option<Person> = db.create("person").await?;
+    db.create(Resource::from("person")).await?;
 
     db.export("backup.surql").await?;
     Ok(())
 }
-
 ```
 
 If an empty tuple is passed in for the file name, the `.export()` method will instead return an async stream of bytes.
 
 ```rust
-#[derive(Debug, Serialize, Deserialize)]
-struct Person {
-    id: Thing,
-}
-
 use futures::StreamExt;
-use serde::{Deserialize, Serialize};
 use surrealdb::engine::any::connect;
-use surrealdb::sql::Thing;
+use surrealdb::opt::auth::Root;
+use surrealdb::opt::Resource;
 
 #[tokio::main]
 async fn main() -> surrealdb::Result<()> {
     let db = connect("http://localhost:8000").await?;
+    db.signin(Root {
+        username: "root",
+        password: "root",
+    })
+    .await?;
     db.use_ns("ns").use_db("db").await?;
 
     // Create a `person` record
-    let _: Option<Person> = db.create("person").await?;
+    db.create(Resource::from("person")).await?;
 
     let mut stream = db.export(()).await?;
 

src/content/doc-sdk-rust/methods/import.mdx

@@ -13,17 +13,23 @@ Restores the database from a file.
 > WebSocket connections currently do not currently support exports and imports. Be sure to use an HTTP endpoint when using this method.
 
 ```rust title="Method Syntax"
-db.authenticate(token)
+db.import(source)
 ```
 
 ### Example usage
 
 ```rust
 use surrealdb::engine::any::connect;
+use surrealdb::opt::auth::Root;
 
 #[tokio::main]
 async fn main() -> surrealdb::Result<()> {
     let db = connect("http://localhost:8000").await?;
+    db.signin(Root {
+        username: "root",
+        password: "root",
+    })
+    .await?;
     db.use_ns("ns").use_db("db").await?;
     db.import("backup.surql").await?;
     Ok(())

src/content/doc-sdk-rust/methods/index.mdx

@@ -36,7 +36,7 @@ Most methods in the SurrealDB SDK involve either working with or creating an ins
             <td scope="row" data-label="Description">Assigns a value as a parameter for this connection</td>
         </tr>
 		<tr>
-			<td scope="row" data-label="Function"><a href="/docs/sdk/rust/methods/use"> <code> db.use()</code></a></td>
+			<td scope="row" data-label="Function"><a href="/docs/sdk/rust/methods/use"> <code> db.use_ns().use_db()</code></a></td>
 			<td scope="row" data-label="Description">Switch to a specific namespace and database</td>
 		</tr>
         <tr>
@@ -172,9 +172,5 @@ Most methods in the SurrealDB SDK involve either working with or creating an ins
             <td scope="row" data-label="Function"><a href="/docs/sdk/rust/methods/version"> <code>db.version()</code></a></td>
             <td scope="row" data-label="Description">Returns the current database version</td>
         </tr>
-        <tr>
-            <td scope="row" data-label="Function"><a href="/docs/sdk/rust/methods/wait_for"> <code>db.import()</code></a></td>
-            <td scope="row" data-label="Description">Waits for a certain event to occur before proceeding</td>
-        </tr>
     </tbody>
-</table>
+</table>

src/content/doc-sdk-rust/methods/init.mdx

@@ -8,6 +8,7 @@ description: The .init() method initializes a new unconnected instance.
 # `init()`
 
 The .init() method initializes a new unconnected instance of the client.
+This is typically used to create a global, static instance of the client.
 
 ```rust title="Method Syntax"
 Surreal::init()
@@ -16,35 +17,36 @@ Surreal::init()
 ### Example usage
 
 ```rust
+use std::sync::LazyLock;
 use surrealdb::engine::remote::ws::{Client, Ws};
 use surrealdb::Surreal;
 
+static DB: LazyLock<Surreal<Client>> = LazyLock::new(Surreal::init);
+
 #[tokio::main]
 async fn main() -> surrealdb::Result<()> {
-    let db: Surreal<Client> = Surreal::init();
     // Connect to the database
-    db.connect::<Ws>("127.0.0.1:8000").await?;
+    DB.connect::<Ws>("127.0.0.1:8000").await?;
     Ok(())
 }
 ```
 
-`Surreal::init()` by default will create an instance of `Surreal<Any>`, allowing you to choose at runtime which way to connect.
+`Surreal::init()` can also be used to create an instance of `Surreal<Any>`, allowing you to choose at runtime which way to connect.
 
 ```rust
 use std::env;
-
+use std::sync::LazyLock;
 use surrealdb::engine::any::Any;
 use surrealdb::Surreal;
 
+static DB: LazyLock<Surreal<Any>> = LazyLock::new(Surreal::init);
+
 #[tokio::main]
 async fn main() -> surrealdb::Result<()> {
-    let db: Surreal<Any> = Surreal::init();
-
-    if let Ok(path) = env::var("DB_ENDPOINT") {
-        db.connect(path).await?;
-    } else {
-        db.connect("mem://").await?;
-    };
+    // Choose an endpoint at runtime using the `DB_ENDPOINT` environment variable
+    // or fallback to the memory engine.
+    let endpoint = env::var("DB_ENDPOINT").unwrap_or_else(|_| "mem://".to_owned());
+    DB.connect(endpoint).await?;
     Ok(())
 }
 ```