version bump

springtime-migrate-refinery/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "springtime-migrate-refinery"
-version = "0.1.0"
+version = "0.2.0"
 edition.workspace = true
 authors.workspace = true
 description = "SQL migration framework based on dependency injection."

springtime-migrate-refinery/README.md

@@ -1,4 +1,4 @@
-# Springtime Migrate Reginery
+# Springtime Migrate Refinery
 
 [![crates.io version](https://img.shields.io/crates/v/springtime-migrate-refinery.svg)](https://crates.io/crates/springtime-migrate-refinery)
 ![build status](https://github.com/krojew/springtime/actions/workflows/rust.yml/badge.svg)
@@ -19,3 +19,61 @@ Note: in addition to this crate, you need to also import
 * File-based and code-based migrations
 * Automatic migration application on startup for configured db clients
 * All `refinery` db clients supported
+
+## Basic usage
+
+As with `refinery`, the basic usage consists of creating or embedding migrations
+and providing a runner for desired database.
+
+The following example assumes familiarity with
+[springtime](https://crates.io/crates/springtime) and
+[springtime-di](https://crates.io/crates/springtime-di).
+
+```rust
+use refinery_core::Runner;
+use springtime::application;
+use springtime::future::{BoxFuture, FutureExt};
+use springtime_di::instance_provider::ErrorPtr;
+use springtime_migrate_refinery::migration::embed_migrations;
+use springtime_migrate_refinery::runner::MigrationRunnerExecutor;
+
+// this is all that's needed to embed sql migrations from the given folder (the default path is
+// "migrations")
+embed_migrations!("examples/migrations");
+
+// this is a migration source, which can provide migrations from code, instead of sql files
+#[derive(Component)]
+struct ExampleMigrationSource;
+
+// register the source with dependency injection
+#[component_alias]
+impl MigrationSource for ExampleMigrationSource {
+    fn migrations(&self) -> Result<Vec<Migration>, ErrorPtr> {
+        Migration::unapplied("V00__test", "CREATE TABLE test (id INTEGER PRIMARY KEY);")
+            .map(|migration| vec![migration])
+            .map_err(|error| Arc::new(error) as ErrorPtr)
+    }
+}
+
+// refinery migration runner needs a concrete DB client to run - this necessitates an abstraction
+// layer; please see MigrationRunnerExecutor for details
+struct ExampleMigrationRunnerExecutor;
+
+impl MigrationRunnerExecutor for ExampleMigrationRunnerExecutor {
+    fn run_migrations(&self, _runner: &Runner) -> BoxFuture<'_, Result<(), ErrorPtr>> {
+        // run migrations here with the given runner
+        async { Ok(()) }.boxed()
+    }
+}
+
+// note: for the sake of simplicity, errors are unwrapped, rather than gracefully handled
+#[tokio::main]
+async fn main() {
+    // create our application, which will run refinery migration runner before other runners
+    let mut application =
+        application::create_default().expect("unable to create default application");
+
+    // will run migrations from the "migrations" folder if MigrationRunnerExecutor(s) are available
+    application.run().await.expect("error running application");
+}
+```

springtime-migrate-refinery/src/migration.rs

@@ -9,9 +9,9 @@ use springtime_di::injectable;
 /// Embed migrations from a given path (`migrations` by default). Path is inspected for `*.sql`
 /// files, which are converted into [MigrationSources](MigrationSource).
 ///
-/// ```ignore
+/// ```
 /// use springtime_migrate_refinery::migration::embed_migrations;
-/// embed_migrations!("path/to/migrations");
+/// embed_migrations!("examples/migrations");
 /// ```
 pub use springtime_migrate_refinery_macros::embed_migrations;