Prep for 0.8 (#325)

Author: Electron100

Cargo.lock

@@ -18,14 +18,14 @@ members = [
 edition = "2021"
 license = "MIT OR Apache-2.0"
 repository = "https://github.com/Electron100/butane"
-version = "0.7.0"
+version = "0.8.0"
 
 [workspace.dependencies]
 async-trait = "0.1"
-butane = { version = "0.7", path = "butane" }
+butane = { version = "0.8", path = "butane" }
 butane_cli = { path = "butane_cli" }
-butane_core = { version = "0.7", path = "butane_core" }
-butane_codegen = { version = "0.7", path = "butane_codegen" }
+butane_core = { version = "0.8", path = "butane_core" }
+butane_codegen = { version = "0.8", path = "butane_codegen" }
 butane_test_helper = { path = "butane_test_helper", default-features = false }
 butane_test_macros = { path = "butane_test_macros" }
 cfg-if = "^1.0"

Cargo.toml

@@ -7,6 +7,10 @@ deliberately follow the same goal as [Diesel's getting-started
 guide](https://diesel.rs/guides/getting-started/): building the
 database portions of a blog.
 
+This guide shows a synchronous example, but Butane now supports
+async. Code for an async equivalent can be found at
+[examples/getting_started_async](https://github.com/Electron100/butane/tree/master/examples/getting_started_async)
+
 Let's begin by creating a new rust project
 
 ``` shell
@@ -17,7 +21,7 @@ In `Cargo.toml`, add a dependency on Butane:
 
 ``` toml
 [dependencies]
-butane = { version = "0.7", features=["pg", "sqlite"] }
+butane = { version = "0.8", features=["pg", "sqlite"] }
 ```
 
 This guide will focus on using SQLite initially, and use "pg" for
@@ -65,8 +69,7 @@ yet. Let's define some _models_ for our blog objects (in `src/models.rs`). We'll
 the Blog itself.
 
 ``` rust
-use butane::prelude::*;
-use butane::{model, ForeignKey, Many, ObjectState};
+use butane::{model, AutoPk, ForeignKey, Many, ObjectState};
 
 #[model]
 #[derive(Debug, Default)]
@@ -88,14 +91,7 @@ The `#[model]` attribute does the heavy lifting here:
 
 1. It generates automatic `impl`s of [`butane::DataResult`] and
    [`butane::DataObject`].
-2. It adds an additional field `state: butane::ObjectState` used to
-   store internal Butane state information. In general, we can ignore
-   this field, but it must be initialized when the struct is
-   constructed and there may not be another field named `state`,
-   although it is acceptable to manually include the `state:
-   ObjectState` field in the struct definition to make its presence
-   more obvious (and rust-analyzer happier).
-3. It tells Butane that instances of this struct should be represented in the
+2. It tells Butane that instances of this struct should be represented in the
    database, recording migration info (more on this later).
 
 The `id` field is special -- it's the primary key. All models must
@@ -121,28 +117,30 @@ pub struct Post {
     pub blog: ForeignKey<Blog>,
     pub tags: Many<Tag>,
     pub byline: Option<String>,
-    // listed for clarity, generated automatically if omitted
-    state: butane::ObjectState,
 }
 impl Post {
     pub fn new(blog: &Blog, title: String, body: String) -> Self {
         Post {
-            id: -1,
+            id: AutoPk::uninitialized(),
             title,
             body,
             published: false,
-            blog: blog.into(),
             tags: Many::default(),
+            blog: blog.into(),
             byline: None,
-            state: ObjectState::default(),
+            likes: 0,
         }
     }
 }
 ```
 
 Each post is associated with a single blog, represented by the
-`ForeignKey<Blog>`. Posts and tags, however, have a many-to-many
-relationship, represented here by `Many<Tag>`.
+`ForeignKey<Blog>`. Here we use `blog.into()` to construct the
+`ForeignKey`. If we had the `id` of the blog but not a `Blog` object
+itself, we could have used `ForeignKey::from_pk` instead.
+
+Posts and tags, on the other hand, have a many-to-many relationship, represented
+here by `Many<Tag>`.
 
 The Tag model itself is trivial
 
@@ -155,10 +153,7 @@ pub struct Tag {
 }
 impl Tag {
     pub fn new(tag: impl Into<String>) -> Self {
-        Tag {
-            tag: tag.into(),
-            ..Default::default()
-        }
+        Tag { tag: tag.into() }
     }
 }
 ```
@@ -226,8 +221,7 @@ pub fn create_post(conn: &Connection, blog: &Blog, title: String, body: String)
 
 The `butane::prelude::*` import brings some common Butane traits into
 scope. If you'd prefer to avoid star-imports, you can import the
-necessary traits explicitly (in this case `use butane::{DataObject,
-DataResult};`)
+necessary traits explicitly (in this case `use butane::{query::QueryOpsSync, DataObjectOpsSync, DataResult};`)
 
 We don't need to create a new blog every time, if we have an existing
 one we want to reuse it (for simplicity we'll only add one blog in
@@ -504,9 +498,9 @@ Now compiling the code will include the migrations, however we need to update th
 to use these migrations:
 
 ``` rust
-pub fn establish_connection() -> Connection {
-    use butane::migrations::Migrations;
+use butane::migrations::Migrations;
 
+pub fn establish_connection() -> Connection {
     let mut connection = butane::db::connect(&ConnectionSpec::load(".butane/connection.json").unwrap()).unwrap();
     let migrations = butane_migrations::get_migrations().unwrap();
     migrations.migrate(&mut connection).unwrap();

docs/getting-started.md

@@ -1,13 +1,13 @@
 //! Common helpers for the getting_started example CLI.
 
-#![deny(missing_docs)]
-
 pub mod butane_migrations;
 pub mod models;
 
 use butane::db::{Connection, ConnectionSpec};
 use butane::migrations::Migrations;
 use butane::prelude::*;
+// If you prefer not to use the prelude, you could use the following instead.
+// use butane::{query::QueryOpsSync, DataObjectOpsSync, DataResult};
 use models::{Blog, Post};
 
 /// Load a [Connection].

examples/getting_started/src/lib.rs

@@ -1,7 +1,6 @@
 //! Models for the getting_started example.
 
-use butane::AutoPk;
-use butane::{model, ForeignKey, Many};
+use butane::{model, AutoPk, ForeignKey, Many};
 
 /// Blog metadata.
 #[model]
@@ -16,8 +15,8 @@ impl Blog {
     /// Create a new Blog.
     pub fn new(name: impl Into<String>) -> Self {
         Blog {
+            id: AutoPk::uninitialized(),
             name: name.into(),
-            ..Default::default()
         }
     }
 }