Skip to content

Commit d4660bc

Browse files
juntaojuntao
committed
Add new socket API docs
Signed-off-by: Michael Yuan <[email protected]>
1 parent 697013b commit d4660bc

File tree

3 files changed

+219
-15
lines changed

3 files changed

+219
-15
lines changed

‎docs/develop/rust/database/my_sql_driver.md

+181-13
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ The database connection is necessary for today's enterprise development. WasmEdg
88

99
<!-- prettier-ignore -->
1010
:::note
11-
Before we start, ensure [you have Rust and WasmEdge installed](../setup.md). If you are connecting to a remote MySQL database using TLS, you will need to [install the TLS plugin](../../../start/install.md#tls-plug-in) for WasmEdge as well.
11+
Before we start, ensure [you have Rust and WasmEdge installed](../setup.md).
1212
:::
1313

1414
## Run the example
@@ -20,28 +20,196 @@ git clone https://github.com/WasmEdge/wasmedge-db-examples
2020
cd wasmedge-db-examples/mysql_async
2121

2222
# Compile the rust code into WASM
23-
cargo build --target wasm32-wasi --release
23+
RUSTFLAGS="--cfg wasmedge --cfg tokio_unstable" cargo build --target wasm32-wasi --release
2424

2525
# Execute MySQL statements against a MySQL database at mysql://user:[email protected]:3306
2626
wasmedge --env "DATABASE_URL=mysql://user:[email protected]:3306/mysql" target/wasm32-wasi/release/crud.wasm
2727
```
2828

29-
To use TLS, you will need to turn on the `default-rustls` feature in `Cargo.toml`.
30-
31-
```toml
32-
mysql_async_wasi = { version = "0.31", features = [ "default-rustls" ] }
33-
```
34-
29+
To use TLS, you will need to turn on the `default-rustls` feature on the `mysql_async` crate in `Cargo.toml`.
3530
Then, run the application as follows.
3631

3732
```toml
3833
# Execute MySQL statements against an AWS RDS database that requires TLS
3934
wasmedge --env "DATABASE_SSL=1" --env "DATABASE_URL=mysql://user:[email protected]:3306/mysql" crud.wasm
4035
```
4136

42-
## Code explanation
37+
## Configuration
38+
39+
In order to compile the `mysql_async` and `tokio` crates, we will need to apply two patches to add
40+
WasmEdge-specific socket APIs to those crates. The following example shows that the TLS connection is enabled.
41+
42+
```
43+
[patch.crates-io]
44+
tokio = { git = "https://github.com/second-state/wasi_tokio.git", branch = "v1.36.x" }
45+
socket2 = { git = "https://github.com/second-state/socket2.git", branch = "v0.5.x" }
46+
47+
[dependencies]
48+
mysql_async = { version = "0.34", default-features=false, features = [ "default-rustls" ], git="https://github.com/blackbeam/mysql_async.git" }
49+
zstd-sys = "=2.0.9"
50+
tokio = { version = "1", features = [ "io-util", "fs", "net", "time", "rt", "macros"] }
51+
```
52+
53+
## Code example
54+
55+
The following code shows how to connect to a MySQL database server, and then insert, update, and delete records using SQL
56+
statements.
57+
58+
Connect to a MySQL database.
59+
60+
```
61+
// Below we create a customized connection pool
62+
let opts = Opts::from_url(&*get_url()).unwrap();
63+
let mut builder = OptsBuilder::from_opts(opts);
64+
if std::env::var("DATABASE_SSL").is_ok() {
65+
builder = builder.ssl_opts(SslOpts::default());
66+
}
67+
// The connection pool will have a min of 5 and max of 10 connections.
68+
let constraints = PoolConstraints::new(5, 10).unwrap();
69+
let pool_opts = PoolOpts::default().with_constraints(constraints);
70+
71+
let pool = Pool::new(builder.pool_opts(pool_opts));
72+
let mut conn = pool.get_conn().await.unwrap();
73+
```
74+
75+
Create a table on the connected database.
76+
77+
```
78+
// create table if no tables exist
79+
let result = r"SHOW TABLES LIKE 'orders';"
80+
.with(())
81+
.map(&mut conn, |s: String| String::from(s))
82+
.await?;
83+
84+
if result.len() == 0 {
85+
// table doesn't exist, create a new one
86+
r"CREATE TABLE orders (order_id INT, production_id INT, quantity INT, amount FLOAT, shipping FLOAT, tax FLOAT, shipping_address VARCHAR(20));".ignore(&mut conn).await?;
87+
println!("create new table");
88+
} else {
89+
// delete all data from the table.
90+
println!("delete all from orders");
91+
r"DELETE FROM orders;".ignore(&mut conn).await?;
92+
}
93+
```
94+
95+
Insert some records into the MySQL database using SQL.
96+
97+
```
98+
let orders = vec![
99+
Order::new(1, 12, 2, 56.0, 15.0, 2.0, String::from("Mataderos 2312")),
100+
Order::new(2, 15, 3, 256.0, 30.0, 16.0, String::from("1234 NW Bobcat")),
101+
Order::new(3, 11, 5, 536.0, 50.0, 24.0, String::from("20 Havelock")),
102+
Order::new(4, 8, 8, 126.0, 20.0, 12.0, String::from("224 Pandan Loop")),
103+
Order::new(5, 24, 1, 46.0, 10.0, 2.0, String::from("No.10 Jalan Besar")),
104+
];
105+
106+
r"INSERT INTO orders (order_id, production_id, quantity, amount, shipping, tax, shipping_address)
107+
VALUES (:order_id, :production_id, :quantity, :amount, :shipping, :tax, :shipping_address)"
108+
.with(orders.iter().map(|order| {
109+
params! {
110+
"order_id" => order.order_id,
111+
"production_id" => order.production_id,
112+
"quantity" => order.quantity,
113+
"amount" => order.amount,
114+
"shipping" => order.shipping,
115+
"tax" => order.tax,
116+
"shipping_address" => &order.shipping_address,
117+
}
118+
}))
119+
.batch(&mut conn)
120+
.await?;
121+
```
122+
123+
Query the database.
124+
125+
```
126+
// query data
127+
let loaded_orders = "SELECT * FROM orders"
128+
.with(())
129+
.map(
130+
&mut conn,
131+
|(order_id, production_id, quantity, amount, shipping, tax, shipping_address)| {
132+
Order::new(
133+
order_id,
134+
production_id,
135+
quantity,
136+
amount,
137+
shipping,
138+
tax,
139+
shipping_address,
140+
)
141+
},
142+
)
143+
.await?;
144+
dbg!(loaded_orders.len());
145+
dbg!(loaded_orders);
146+
```
147+
148+
Delete some records from the database.
149+
150+
```
151+
// // delete some data
152+
r"DELETE FROM orders WHERE order_id=4;"
153+
.ignore(&mut conn)
154+
.await?;
155+
156+
// query data
157+
let loaded_orders = "SELECT * FROM orders"
158+
.with(())
159+
.map(
160+
&mut conn,
161+
|(order_id, production_id, quantity, amount, shipping, tax, shipping_address)| {
162+
Order::new(
163+
order_id,
164+
production_id,
165+
quantity,
166+
amount,
167+
shipping,
168+
tax,
169+
shipping_address,
170+
)
171+
},
172+
)
173+
.await?;
174+
dbg!(loaded_orders.len());
175+
dbg!(loaded_orders);
176+
```
177+
178+
Update records in the MySQL database.
179+
180+
```
181+
// // update some data
182+
r"UPDATE orders
183+
SET shipping_address = '8366 Elizabeth St.'
184+
WHERE order_id = 2;"
185+
.ignore(&mut conn)
186+
.await?;
187+
// query data
188+
let loaded_orders = "SELECT * FROM orders"
189+
.with(())
190+
.map(
191+
&mut conn,
192+
|(order_id, production_id, quantity, amount, shipping, tax, shipping_address)| {
193+
Order::new(
194+
order_id,
195+
production_id,
196+
quantity,
197+
amount,
198+
shipping,
199+
tax,
200+
shipping_address,
201+
)
202+
},
203+
)
204+
.await?;
205+
dbg!(loaded_orders.len());
206+
dbg!(loaded_orders);
207+
```
208+
209+
Close the database connection.
210+
211+
```
212+
drop(conn);
213+
pool.disconnect().await.unwrap();
214+
```
43215

44-
<!-- prettier-ignore -->
45-
:::info
46-
Work in Progress
47-
:::

‎docs/develop/rust/setup.md

+37-1
Original file line numberDiff line numberDiff line change
@@ -32,4 +32,40 @@ To build a WASM file running in server-side WebAssembly like WasmEdge, we need t
3232
rustup target add wasm32-wasi
3333
```
3434

35-
That's it. Go to the following chapters to build and compile Rust programs in action.
35+
## Special notes
36+
37+
### Async networking with tokio
38+
39+
WasmEdge supports async networking APIs provided by [Tokio](https://tokio.rs/) and related crates. If you have tokio in your `Cargo.toml`, you
40+
need to add a few config flags to help the Rust compiler choose the correct feature branches in the library source code. Here is an example of `cargo build` command for
41+
compiling a tokio app to Wasm.
42+
43+
```
44+
RUSTFLAGS="--cfg wasmedge --cfg tokio_unstable" cargo build --target wasm32-wasi --release
45+
```
46+
47+
Alternatively, you could add these lines to the `.cargo/config.toml` file.
48+
49+
```
50+
[build]
51+
target = "wasm32-wasi"
52+
rustflags = ["--cfg", "wasmedge", "--cfg", "tokio_unstable"]
53+
```
54+
55+
### Compile Rust TLS on MacOS
56+
57+
The standard `cargo` toolchain can support the [Rust TLS](https://github.com/rustls/rustls) library on Linux. However,
58+
on MacOS, you need a special version of the Clang tool, released from the official [wasi-sdk](https://github.com/WebAssembly/wasi-sdk), in order to support TLS libraries.
59+
60+
> When you compile Rust TLS source code to Wasm on Linux, the result Wasm file is cross-platform and can run correctly on any platform with WasmEdge installed. This section is only applicable when you need to **compile** Rust TLS source code on MacOS.
61+
62+
[Download the latest wasi-sdk release](https://github.com/WebAssembly/wasi-sdk/releases) for your platform and
63+
expand it into a directory. Point the `WASI_SDK_PATH` variable to this directory and export a `CC` variable for the default Clang.
64+
65+
```
66+
export WASI_SDK_PATH /path/to/wasi-sdk-22.0
67+
export CC="${WASI_SDK_PATH}/bin/clang --sysroot=${WASI_SDK_PATH}/share/wasi-sysroot"
68+
```
69+
70+
That's it. Now you can use the `cargo` tools on MacOS to compile tokio libraries with `rust-tls` feature turned on.
71+

‎docs/start/install.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -294,7 +294,7 @@ Then, go to [TensorFlow interface in Rust chapter](../develop/rust/wasinn/tf_plu
294294

295295
<!-- prettier-ignore -->
296296
:::note
297-
The Tensorflow Lite plugin is being deprecated from WasmEdge 0.14.0. We now compile TLS functions directly into Wasm for better portability.
297+
The WasmEdge TLS plugin is being deprecated from WasmEdge 0.14.0. We now compile TLS functions directly into Wasm for better portability.
298298
:::note
299299

300300
The WasmEdge TLS plug-in utilizes the native OpenSSL library to support HTTPS and TLS requests from WasmEdge sockets. To install WasmEdge with the TLS plug-in, run the following command.

0 commit comments

Comments
 (0)