From c766042262431ffbfe7681bc4d25558373111b72 Mon Sep 17 00:00:00 2001
From: Dmitriy Pleshevskiy <dmitriy@ideascup.me>
Date: Sun, 13 Jun 2021 01:25:45 +0300
Subject: [PATCH] chore: add basic example

---
 migra/README.md        | 35 +++++++++++++++++++++++++++++++++--
 migra/src/lib.rs       | 35 +++++++++++++++++++++++++++++++++++
 migra/src/migration.rs |  2 ++
 3 files changed, 70 insertions(+), 2 deletions(-)

diff --git a/migra/README.md b/migra/README.md
index 0284a2e..9556f01 100644
--- a/migra/README.md
+++ b/migra/README.md
@@ -32,9 +32,40 @@ authors = ["Me <user@rust-lang.org>"]
 migra = { version = "1.0", features = ["postgres"] }
 ```
 
-### Usage
+## Basic usage
 
-For more information about the crate, please read doc.
+**Note:** This example requires to enable `sqlite` feature.
+
+```rust
+use migra::clients::{OpenDatabaseConnection, SqliteClient};
+use migra::managers::{ManageTransaction, ManageMigrations};
+
+fn main() -> migra::Result<()> {
+    let mut client = SqliteClient::new("./tasks.db")?;
+
+    client.create_migrations_table()?;
+
+    let mut migrations = client.get_applied_migrations()?;
+
+    client
+        .begin_transaction()
+        .and_then(|_| {
+            migrations.should_run_upgrade_migration(
+                &mut client,
+                "20210615_initial_migration",
+                r#"CREATE TABLE IF NOT EXISTS tasks (
+                    title TEXT NOT NULL
+                );"#,
+            )?;
+
+            Ok(())
+        })
+        .and_then(|res| client.commit_transaction().and(Ok(res)))
+        .or_else(|err| client.rollback_transaction().and(Err(err)));
+
+    Ok(())
+}
+```
 
 ### Supported databases
 
diff --git a/migra/src/lib.rs b/migra/src/lib.rs
index fce3e33..53545cb 100644
--- a/migra/src/lib.rs
+++ b/migra/src/lib.rs
@@ -26,6 +26,41 @@
 //! migra = { version = "1.0", features = ["postgres"] }
 //! ```
 //!
+//! ## Basic usage
+//!
+//! **Note:** This example requires to enable `sqlite` feature.
+//!
+//! ```rust
+//! use migra::clients::{OpenDatabaseConnection, SqliteClient};
+//! use migra::managers::{ManageTransaction, ManageMigrations};
+//!
+//! fn main() -> migra::Result<()> {
+//!     let mut client = SqliteClient::new("./tasks.db")?;
+//!
+//!     client.create_migrations_table()?;
+//!
+//!     let mut migrations = client.get_applied_migrations()?;
+//!
+//!     client
+//!         .begin_transaction()
+//!         .and_then(|_| {
+//!             migrations.should_run_upgrade_migration(
+//!                 &mut client,
+//!                 "20210615_initial_migration",
+//!                 r#"CREATE TABLE IF NOT EXISTS tasks (
+//!                     title TEXT NOT NULL
+//!                 );"#,
+//!             )?;
+//!
+//!             Ok(())
+//!         })
+//!         .and_then(|res| client.commit_transaction().and(Ok(res)))
+//!         .or_else(|err| client.rollback_transaction().and(Err(err)));
+//!
+//!     Ok(())
+//! }
+//! ```
+//!
 //! ### Supported databases
 //!
 //! | Database Client | Feature      |
diff --git a/migra/src/migration.rs b/migra/src/migration.rs
index c0c712b..460792e 100644
--- a/migra/src/migration.rs
+++ b/migra/src/migration.rs
@@ -109,6 +109,7 @@ impl List {
     /// # Example
     ///
     /// ```rust
+    /// # use migra::migration::List;
     /// # let mut list = List::new();
     /// list.push_name("name");
     /// # assert_eq!(list, List::from(vec!["name"]));
@@ -116,6 +117,7 @@ impl List {
     ///
     /// Is identical to the following
     /// ```rust
+    /// # use migra::migration::{List, Migration};
     /// # let mut list = List::new();
     /// list.push(Migration::new("name"));
     /// # assert_eq!(list, List::from(vec!["name"]));