flyway 0.3.0

Main crate of the Flyway-rs project. Includes `migrations` macro and the `MigrationRunner`
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98

# flyway-rs copy from db-up

`flyway` is a collection of Rust crates for loading and executing database
migrations.

It supposed to be an alternative to [refinery](https://github.com/rust-db/refinery)
and was created because `refinery` is pretty closed when it comes to database drivers. Basically
it is not possible to create database driver crates for `refinery` without creating either a
fork or including the driver inside the `refinery` crate. The reason is that the
`refinery::Migration::applied(...)` method is not public, which prevents other crates from implementing
the `refinery::AsyncMigrate` trait and reading [this issue](https://github.com/rust-db/refinery/issues/248)
it seems the authors are not motivated to change this behaviour.

`flyway` consists of multiple crates:
* Top-level crates:
    * `flyway`: The main crate. Contains the migration runner and re-exports necessary
      macros and structs from other flyway crates.
    * `flyway-rbatis`: A driver for executing DB migrations via the
      [Rbatis](https://github.com/rbatis/rbatis) database library.
* Other crates:
    * `flyway-codegen`: Contains the `migrations` attribute macro
    * `flyway-sql-changelog`: Contains the `ChangelogFile` struct that can load
      SQL files and split them into separate, annotated statements
      via a `SqlStatementIterator`.

## Status

This crate has some known (and probably some unknown) limitations and stability issues:

* The transaction management is not finished yet. At the moment, only a
  "one transaction per changelog" mode is implemented, but no "one transaction for all changes"
  mode. I'm not sure if anyone will need the latter, but it i plan to implement it at some point.
* The "last successful version" is not set correctly at many places, especially when producing
  errors.
* The `iter()` implementation for `ChangelogFile` is not conforming to the Rust standards
  yet.
* For now, there is only an Rbatis driver implementation available.
* The Rbatis driver in `flyway-rbatis` uses one set of queries for all database drivers supported
  by Rbatis. As far as i can tell from e.g. `refinery`, some database systems (specifically MSSQL)
  support or even need a different syntax for state management.
* More examples should be added.
* More tests should be added.

## Usage

All the crates in this project are libraries. The included tests can be started via:

```sh
~$ cd flyway
~/flyway$ cargo test
```

To use the crates inside your project, the following steps should be taken:

1. Include the necessary crates in your `Cargo.toml` (get available versions
   from [crates.io](https://crates.io/crates/flyway)):
```toml
# Add the flyway dependency
[dependency.flyway]
version = "<version>"

# Add the flyway-rbatis dependency in order to run migrations via Rbatis. At the time
# of writing, this is the only supported database driver.
[dependency.flyway-rbatis]
version = "<version>"

# Add Rbatis dependencies ...
```
2. E.g in your `main.rs`:
```rust
use flyway::{MigrationExecutor, MigrationState, MigrationStateManager, MigrationStore, migrations, MigrationRunner};
use flyway_rbatis::RbatisMigrationDriver;
use rbatis::Rbatis;

// Load migrations (SQL files) from `examples/migrations` and make them available via
// `Migrations::changelog()`. The generated class can be used for `MigrationRunner::migrate(...)`.
#[migrations("examples/migrations")]
pub struct Migrations {
}

async fn run(rbatis: Arc<Rbatis>) -> Result<()> {
    let migration_driver = Arc::new(RbatisMigrationDriver::new(rbatis.clone(), None));
    let migration_runner = MigrationRunner::new(
        Migrations {},
        migration_driver.clone(),
        migration_driver.clone()
    );
    migration_runner.migrate().await?;
}

// Add main method that creates an `Rbatis` instance and calls the `run(...)` method.
// ...

```

# License

The project is licensed under the [MIT](LICENSE).