Add Async Support

Cargo.toml

@@ -6,9 +6,11 @@ members = [
   "butane_codegen",
   "butane_core",
   "butane_test_helper",
+  "butane_test_macros",
   "example",
   "examples/newtype",
   "examples/getting_started",
+  "examples/getting_started_async",
 ]
 
 [workspace.package]
@@ -18,23 +20,25 @@ repository = "https://github.com/Electron100/butane"
 version = "0.7.0"
 
 [workspace.dependencies]
+async-trait = "0.1"
 butane = { version = "0.7", path = "butane" }
 butane_cli = { path = "butane_cli" }
 butane_core = { version = "0.7", path = "butane_core" }
 butane_codegen = { version = "0.7", path = "butane_codegen" }
 butane_test_helper = { path = "butane_test_helper" }
+butane_test_macros = { path = "butane_test_macros" }
 cfg-if = "^1.0"
 chrono = { version = "0.4.25", default-features = false, features = [
   "serde",
   "std",
 ] }
+crossbeam-channel = "0.5"
 env_logger = "0.11"
 fake = "2.6"
 log = "0.4"
 nonempty = "0.10"
 once_cell = "1.5.2"
 paste = "1.0.11"
-postgres = "0.19"
 proc-macro2 = { version = "1.0", default-features = false }
 quote = { version = "1.0", default-features = false }
 r2d2 = "0.8"
@@ -45,8 +49,17 @@ serde_json = "1.0"
 sqlparser = "0.44"
 syn = { version = "2", features = ["extra-traits", "full"] }
 tempfile = "3.10"
+tokio = { version = "1"}
+tokio-postgres = "0.7"
+tokio-test = { version = "0.4"}
 uuid = "1.2"
 
+# Switch back to crates.io version once one is published containing
+# the referenced commit. Anything newer than 0.2.4 should have it.
+[workspace.dependencies.maybe-async-cfg]
+git = "https://github.com/nvksv/maybe-async-cfg.git"
+rev = "b35f2f42e9b12a25fc731376fe6cdcf41869b2da"
+
 [workspace.metadata.release]
 allow-branch = ["master"]
 push = false

Makefile

@@ -16,7 +16,7 @@ lint :
 
 lint-ci : doclint lint spellcheck check-fmt
 
-check : build test doclint lint spellcheck check-fmt
+check : build doclint lint spellcheck check-fmt test
 
 
 test :
@@ -31,12 +31,13 @@ fmt :
 
 check-fmt :
 	$(CARGO_NIGHTLY) fmt --check
+	editorconfig-checker
 
 spellcheck :
 	typos
 
 doclint :
-	RUSTDOCFLAGS="-D warnings" $(CARGO_NIGHTLY) doc --no-deps --all-features
+	RUSTDOCFLAGS="-D warnings" RUSTFLAGS="-A elided_named_lifetimes" $(CARGO_NIGHTLY) doc --no-deps --all-features
 
 doc :
 	cd butane && $(CARGO_NIGHTLY) doc --no-deps --all-features

README.md

@@ -95,6 +95,34 @@ enabled: you will want to enable `sqlite` and/or `pg`:
   the API will win.
 
 ## Migration of Breaking Changes
+### 0.8 (not yet released)
+
+This is a major release which adds Async support. Effort has been made
+to keep the sync experience as unchanged as possible. Async versions
+of many types have been added, but the sync ones generally retain
+their previous names.
+
+In order to allow sync and async code to look as
+similar as possible for types and traits which do not otherwise need
+separate sync and async variants, several "Ops" traits have been
+introduced which contain methods split off from prior types and traits.
+
+For example, if `obj` is an instance of
+[`DataObject`](https://docs.rs/butane/latest/butane/trait.DataObject.html),
+then you may call `obj.save(conn)` (sync) or `obj.save(conn).await`
+(async). The `save` method no longer lives on `DataObject`. Instead,
+you must use either `butane::DataObjectOpsSync` or
+`butane::DataObjectOpsAsync`. Which trait is in scope will determine
+whether the `save` method is sync or async.
+
+The Ops traits are:
+* `DataObjectOpsSync` / `DataObjectOpsAsync` (for use with [`DataObject`](https://docs.rs/butane/latest/butane/trait.DataObject.html))
+* `QueryOpsSync` / `QueryOpsSync` (for use with [`Query`](https://docs.rs/butane/latest/butane/query/struct.Query.html),
+  less commonly needed directly if you use the [`query`](https://docs.rs/butane/latest/butane/macro.query.html) or
+  [`filter`](https://docs.rs/butane/latest/butane/macro.filter.html) macros)
+* `ForeignKeyOpsSync` / `ForeignKeyOpsAsync` (for use with [`ForeignKey`](https://docs.rs/butane/latest/butane/struct.ForeignKey.html))
+* `ManyOpsSync` / `ManyOpsAsync` (for use with [`Many`](https://docs.rs/butane/latest/butane/struct.Many.html))
+
 ### 0.7
 #### `AutoPk`
 Replace model fields like

async_checklist.md

@@ -0,0 +1,13 @@
+* [x] Clean up pattern for sync/async variants. Inconsistent between suffix and module
+* [x] Tests should run against sync and async
+* [x] Ensure Postgres works in sync
+* [x] Re-enable R2D2 for sync
+* [x] Fix `#[async_trait(?Send)]` to set up Send bound again as it's required for e.g. `tokio::spawn`
+* [x] Separate sync and async examples
+* [x] Ensure sqlite works in async
+* [x] Fully support sync too. Using async should not be required
+* [ ] Clean up miscellaneous TODOs
+* [ ] Establish soundness for unsafe sections of AsyncAdapter
+* [ ] Consider publishing `AsyncAdapter` into its own crate
+* [ ] Should async and/or async_adapter be under a separate feature?
+* [ ] Integrate deadpool or bb8 for async connection pool

butane/Cargo.toml

@@ -27,11 +27,13 @@ tls = ["butane_core/tls"]
 uuid = ["butane_codegen/uuid", "butane_core/uuid"]
 
 [dependencies]
+async-trait = { workspace = true }
 butane_codegen = { workspace = true }
 butane_core = { workspace = true }
 
 [dev-dependencies]
 butane_test_helper = { workspace = true }
+butane_test_macros = { workspace = true }
 cfg-if = { workspace = true }
 paste = { workspace = true }
 chrono = { workspace = true }
@@ -41,9 +43,12 @@ geo-types = "0.7"
 log.workspace = true
 nonempty.workspace = true
 quote = { workspace = true }
+maybe-async-cfg.workspace = true
 proc-macro2 = { workspace = true }
 once_cell = { workspace = true }
-postgres = { features = ["with-geo-types-0_7"], workspace = true }
+tokio = { workspace = true, features = ["macros"] }
+tokio-postgres = { features = ["with-geo-types-0_7"], workspace = true }
+tokio-test = { workspace = true }
 rand = { workspace = true }
 r2d2_for_test = { package = "r2d2", version = "0.8" }
 rusqlite = { workspace = true }

butane/src/lib.rs

@@ -9,13 +9,12 @@
 pub use butane_codegen::{butane_type, dataresult, model, FieldType, PrimaryKeyType};
 pub use butane_core::custom;
 pub use butane_core::fkey::ForeignKey;
-pub use butane_core::internal;
-pub use butane_core::many::Many;
+pub use butane_core::many::{Many, ManyOpsAsync, ManyOpsSync};
 pub use butane_core::migrations;
 pub use butane_core::query;
 pub use butane_core::{
-    AsPrimaryKey, AutoPk, DataObject, DataResult, Error, FieldType, FromSql, PrimaryKeyType,
-    Result, SqlType, SqlVal, SqlValRef, ToSql,
+    AsPrimaryKey, AutoPk, DataObject, DataObjectOpsAsync, DataObjectOpsSync, DataResult, Error,
+    FieldType, FromSql, PrimaryKeyType, Result, SqlType, SqlVal, SqlValRef, ToSql,
 };
 
 pub mod db {
@@ -160,23 +159,62 @@ macro_rules! colname {
 #[macro_export]
 macro_rules! find {
     ($dbobj:ident, $filter:expr, $conn:expr) => {
-        butane::query!($dbobj, $filter)
-            .limit(1)
-            .load($conn)
+        butane::query::QueryOpsSync::load(butane::query!($dbobj, $filter).limit(1), $conn)
             .and_then(|mut results| results.pop().ok_or(butane::Error::NoSuchObject))
     };
 }
 
-pub mod prelude {
-    //! Prelude module to improve ergonomics.
-    //!
-    //! Its use is recommended, but not required. If not used, the use
-    //! of butane's macros may require some of its re-exports to be
-    //! used manually.
-    pub use butane_core::db::BackendConnection;
+/// Like [`find`], but for async.
+#[macro_export]
+macro_rules! find_async {
+    ($dbobj:ident, $filter:expr, $conn:expr) => {
+        butane::query::QueryOpsAsync::load(butane::query!($dbobj, $filter).limit(1), $conn)
+            .await
+            .and_then(|mut results| results.pop().ok_or(butane::Error::NoSuchObject))
+    };
+}
 
+mod prelude_common {
     #[doc(no_inline)]
     pub use crate::DataObject;
     #[doc(no_inline)]
     pub use crate::DataResult;
 }
+
+pub mod prelude {
+    //! Prelude module to improve ergonomics. Brings certain traits into scope.
+    //! This module is for sync operation. For asynchronous, see [`super::prelude_async`].
+    //!
+    //! Its use is recommended, but not required.
+
+    pub use super::prelude_common::*;
+
+    pub use butane_core::db::BackendConnection;
+    pub use butane_core::fkey::ForeignKeyOpsSync;
+    pub use butane_core::many::ManyOpsSync;
+    pub use butane_core::query::QueryOpsSync;
+    pub use butane_core::DataObjectOpsSync;
+}
+
+pub mod prelude_async {
+    //! Prelude module to improve ergonomics in async operation. Brings certain traits into scope.
+    //!
+    //! Its use is recommended, but not required.
+    pub use super::prelude_common::*;
+
+    pub use butane_core::db::BackendConnectionAsync;
+    pub use butane_core::fkey::ForeignKeyOpsAsync;
+    pub use butane_core::many::ManyOpsAsync;
+    pub use butane_core::query::QueryOpsAsync;
+    pub use butane_core::DataObjectOpsAsync;
+}
+
+pub mod internal {
+    //! Internals used in macro-generated code.
+    //!
+    //! Do not use directly. Semver-exempt.
+
+    pub use async_trait::async_trait;
+
+    pub use butane_core::internal::*;
+}