Work in progress

Tool to perform snapshot testing on an SQLite database, using rusqlite.

The goal is to expose both data and the schema in the snapshots. It is also compatible with Insta Snapshots

This is experimental software, expect breaking changes between 0.x versions, consistent with the semver rules for Rust.

Background reading on snapshot testing.

• https://ianthehenry.com/posts/my-kind-of-repl/
• https://tigerbeetle.com/blog/2024-05-14-snapshot-testing-for-the-masses/
• https://blog.janestreet.com/the-joy-of-expect-tests/

Version 2.4.1

Documentation

Attempt to fix the docs.rs build which started failing in 2.4.0.

Dependencies

Update some dev dependencies, see git history for details.

Version 2.4.0

Dependencies

Rusqlite was updated from 0.37.0 to 0.38.0. Please see the release notes for 0.38.0, there are a few breaking changes in this one.

Update other dev dependencies, see git history for details.

Features

Rusqlite 0.38 makes the cache statement optional. This feature was used for foreign key checks. The rusqlite_migration library does not enable any features from rusqlite, not even the default one. This way, downstream users can freely chose which feature to enable based on their needs. As a result, rusqlite_migration now handles statement caching for foreign key checks internally now. As side benefit, this also makes caching more efficient: the prepared statement is kept for the minimum time where it is needed and freed immediately, without taking space in the global cache used by rusqlite.

Other

• Use scoped GitHub tokens in actions, with as little privileges as possible.
• Improve test build time by removing some unused optional deps.
• Update most dependencies after a cooldown (this does not apply to security updates).
• Errors don’t use debug output anymore, they should be more friendly to humans. This is not considered a breaking change because Dislay of errors is meant for human consuption and not for flow control in the program.

Version 2.3.0

Dependencies

Rusqlite was updated from 0.36.0 to 0.37.0. Please see the release notes for 0.37.0.

Other

• Misc. clippy fixes
• Minor improvements to the example in the Readme

Version 2.2.0

Features

• Implement the Display trait for M. This makes it easier to print errors pertaining to a particular migration (this feature is planned for the future, in the context of more extensive migration checks)

Dependencies

Rusqlite was updated from 0.35.0 to 0.36.0. Please see the release notes for 0.36.0.

Other

• Update development dependencies
• Improve tests to cover more cases, in particular around downward migrations
• Add docs.rs link to Cargo metadata
• Fix clippy warning in rust 1.87.0

Version 2.2.0 Beta 1

Features

• Implement the Display trait for M. This makes it easier to print errors pertaining to a particular migration (this feature is planned for the future, in the context of more extensive migration checks)

Dependencies

Rusqlite was updated from 0.35.0 to 0.36.0. Please see the release notes for 0.36.0.

Other

• Update development dependencies
• Improve tests to cover more cases, in particular around downward migrations
• Add docs.rs link to Cargo metadata
• Fix clippy warning in rust 1.87.0

Version 2.1.0

Dependencies

Rusqlite was updated from 0.34.0 to 0.34.0. Please see the release notes for 0.35.0.

Version 2.0.0

Breaking changes

Remove the alpha-async-tokio-rusqlite Feature

As the name of the feature suggest, we have had experimental support for async using tokio for a while now. Supporting that feature has been quite a big burden, introducing some duplicated code in the AsyncMigrations struct in particular, as well as a whole set of very similar tests. Plus the benefit of async is limited here, because everything gets executed in a blocking fashion in sqlite anyway.

It turns out that we don’t need the async support in rusqlite_migration for folks to use async libraries. For instance, with tokio-rusqlite, you can define migrations like in the sync context and run:

    async_conn
        .call_unwrap(|conn| MIGRATIONS.to_latest(conn))
        .await?;

See the updated async example for details, in particular why it’s fine to call a method with unwrap in its name.

Make the Builder Finalizer Method Not Generic

On a related note, now that we have removed the AsyncMigrations (see the section right above) struct, we only have Migrations so there is no need for the MigrationsBuilder.finalize method to be generic. Thus we removed the generic argument. To update your code, you can just do this:

-        .finalize::<Migrations>());
+        .finalize());

Remove Migrations::new_iter

This function has been deprecated for a while now, remove it as a part of the major version bump. You can use the standard FromIter trait implementation instead.

Behavior Change

• When the user version field is altered by other code in your application, we are now returning an explicit error (Error::InvalidUserVersion) when this can be detected. Previously, the library would silently misbehave.

Features

• Add the new Migrations::from_slice constructor, which is const and takes a slice, so that it can be constructed in global constant, without using LazyLock or similar. Internally, this is possible because we now use a Cow structure to hold migrations.
• Add Migrations::pending_migrations which returns the number of migrations that would be applied. This is mostly useful to take a backup of the database prior to applying migrations (and do nothing if no migrations will be applied).

Dependencies

Rusqlite was updated from 0.32.1 to 0.34.0. Please see the release notes for 0.34.0 and the release notes for 0.33.0. Tokio Rusqlite was removed as a dependency.

Minimum Rust Version

Rust 1.84.

Moving forward, we expect to keep this aligned with rusqlite itself, now that it has a policy (introduced in october 2024).

Version 2.0.0 Beta 1

Features

• Add the new Migrations::from_slice constructor, which is const and takes a slice, so that it can be constructed in global constant, without using LazyLock or similar. Internally, this is possible because we now use a Cow structure to hold migrations.
• Add Migrations::pending_migrations which returns the number of migrations that would be applied. This is mostly useful to take a backup of the database prior to applying migrations (and do nothing if no migrations will be applied).

Version 2.0.0 Alpha 1

Breaking changes

Remove the alpha-async-tokio-rusqlite Feature

As the name of the feature suggest, we have had experimental support for async using tokio for a while now. Supporting that feature has been quite a big burden, introducing some duplicated code in the AsyncMigrations struct in particular, as well as a whole set of very similar tests. Plus the benefit of async is limited here, because everything gets executed in a blocking fashion in sqlite anyway.

It turns out that we don’t need the async support in rusqlite_migration for folks to use async libraries. For instance, with tokio-rusqlite, you can define migrations like in the sync context and run:

    async_conn
        .call_unwrap(|conn| MIGRATIONS.to_latest(conn))
        .await?;

See the updated async example for details, in particular why it’s fine to call a method with unwrap in its name.

Make the Builder Finalizer Method Not Generic

On a related note, now that we have removed the AsyncMigrations (see the section right above) struct, we only have Migrations so there is no need for the MigrationsBuilder.finalize method to be generic. Thus we removed the generic argument. To update your code, you can just do this:

-        .finalize::<Migrations>());
+        .finalize());

Remove Migrations::new_iter

This function has been deprecated for a while now, remove it as a part of the major version bump. You can use the standard FromIter trait implementation instead.

Behavior Change

• When the user version field is altered by other code in your application, we are now returning an explicit error (Error::InvalidUserVersion) when this can be detected. Previously, the library would silently misbehave.

Dependencies

Rusqlite was updated from 0.32.1 to 0.34.0. Please see the release notes for 0.34.0 and the release notes for 0.33.0. Tokio Rusqlite was removed as a dependency.

Features

• Migrations::new is now const

Minimum Rust Version

Rust 1.84.

Moving forward, we expect to keep this aligned with rusqlite itself, now that it has a policy (introduced in october 2024).

Version 1.3.1

The only change is a fix to the deps.rs badge in the documentation.

Version 1.3.0

Rusqlite was updated from 0.31.0 to 0.32.1. Please see the release notes for 0.32.0 and for 0.32.1. Tokio Rusqlite was updated from 0.5.1 to 0.6.0. Please see the release notes.

Minimum Rust Version

Rust 1.77

Documentation

Various documentation improvements and clarification. In particular, call out that if a rusqlite error is encountered during a migration, the next migrations in the list are not applied.

Other

• Apply minor or patch updates to the dependencies
• Update development dependencies
• Make CI testing more reproducible by forcing the use of Cargo.lock

Version 1.3.0 Beta 1

This reintroduces the async features temporarily removed from Version 1.3.0 Alpha-Without-Tokio 1

Rusqlite was updated from 0.31.0 to 0.32.1. Please see the release notes for 0.32.0 and for 0.32.1. Tokio Rusqlite was updated from 0.5.1 to 0.6.0. Please see the release notes.

Minimum Rust Version

Rust 1.77

Documentation

Various documentation improvements and clarification. In particular, call out that if a rusqlite error is encountered during a migration, the next migrations in the list are not applied.

Other

• Apply minor or patch updates to the dependencies
• Update development dependencies
• Make CI testing more reproducible by forcing the use of Cargo.lock

Version 1.3.0 Alpha-Without-Tokio 1

Major Changes

This is an alpha version to start integrating rusqlite 0.32.1. Unfortunately, at this time, tokio-rusqlite is did not update to rusqlite 0.32.1. So we are temporarily removing the async features, while we figure out a way to bring them back. To be clear, we intend to support the async features going forward, this is a temporary change in a specifically tagged version.

Rusqlite was updated from 0.31.0 to 0.32.1. Please see the release notes for 0.32.0 and for 0.32.1

Minimum Rust Version

Rust 1.77

Documentation

Various documentation improvements and clarification. In particular, call out that if a rusqlite error is encountered during a migration, the next migrations in the list are not applied.

Other

• Apply minor or patch updates to the dependencies
• Update development dependencies
• Make CI testing more reproducible by forcing the use of Cargo.lock

Version 1.2.0

Same code as version 1.2.0-beta.1

Documentation

• Improved the badges a little bit

Version 1.2.0 Beta 1

Small release, mainly to update dependencies.

Minimum Rust Version

Now using edition 2021, but the minimum rust version is still 1.70

New Features

No new features.

Other

• Update rusqlite to 0.31
• Update various development dependencies
• Improve CI build time
• Impove documentation
• Fix some broken examples

See also

Rusqlite was updated from 0.30 to 0.31. Please see its release notes

Version 1.1.0

Same code as version 1.1.0-beta.1

Minimum Rust Version

Rust 1.70

New Features

• Support for tokio-rusqlite behind the feature named alpha-async-tokio-rusqlitethanks to @czocher. See the example. This feature is alpha, meaning that compatibility in future minor versions is not guaranteed.
• Create migrations from directories holding SQL files thanks to @czocher. See the example.
• Add up/down hooks to run custom Rust code during migrations (PR thanks to @matze)
• Add foreign_key_check method to migrations (PR thanks to @Jokler)
• Make Migration functions const (PR thanks to @fkaa)
• Make Migrations serializable (using the Debug serializer) with insta.

Depreciation

• Mark Migrations::from_iter as deprecated

Other

• Documentation improvements
  • Repository metadata improvements
• Code quality improvements
  • Introduce cargo mutants & fix bugs found
  • Clippy warning fixes and other linter improvements
  • Report on test coverage & improve test coverage
  • Add benchmarks
• Made errors returned more precise
• Updated dependencies

See also

Rusqlite was updated from 0.29.0 to 0.30.0. Please see its release notes

Version 1.1.0 Beta 1

⚠️ The APIs exposed in this version may be unstable.

Summing up all the changes from the previous Alpha versions.

Minimum Rust Version

Rust 1.70

New Features

• Support for tokio-rusqlite behind the feature named alpha-async-tokio-rusqlitethanks to @czocher. See the example. This feature is alpha, meaning that compatibility in future minor versions is not guaranteed.
• Create migrations from directories holding SQL files thanks to @czocher. See the example.
• Add up/down hooks to run custom Rust code during migrations (PR thanks to @matze)
• Add foreign_key_check method to migrations (PR thanks to @Jokler)
• Make Migration functions const (PR thanks to @fkaa)
• Make Migrations serializable (using the Debug serializer) with insta.

Depreciation

• Mark Migrations::from_iter as deprecated

Other

• Documentation improvements
  • Repository metadata improvements
• Code quality improvements
  • Introduce cargo mutants & fix bugs found
  • Clippy warning fixes and other linter improvements
  • Report on test coverage & improve test coverage
  • Add benchmarks
• Made errors returned more precise
• Updated dependencies

See also

Rusqlite was updated from 0.29.0 to 0.30.0. Please see its release notes

Version 1.1.0 Alpha 2

⚠️ The APIs exposed in this version may be unstable.

Minimum Rust Version

Rust 1.64

New Features

• Create migrations from directories holding SQL files. See the example.

Depreciation

• Mark Migrations::from_iter as deprecated

Other

• Documentation improvements
• Code quality improvements
  • Introduce cargo mutants & fix bugs found
  • Clippy warning fixes
  • Report on test coverage & improve test coverage
  • Add benchmarks
• Made errors returned more precise
• Update dependencies

Version 1.1.0 Alpha 1

⚠️ The APIs exposed in this version may be unstable.

Minimum Rust Version

Rust 1.61

New Features

• Add up/down hooks to run custom Rust code during migrations (PR thanks to @matze)
  • The purpose of this release is to get feedback on the new API. Please feel free to comment on this discussion!
• Add foreign_key_check method to migrations (PR thanks to @Jokler)
  • Please beware of the follow up work needed on this
• Make Migration functions const (PR thanks to @fkaa)

Other

• CI improvements
• Linter improvements
• Repository metadata improvements
• Documentation improvements
• Dev dependencies update (not dependencies of the library when used in another crate)

Version 1.0.2

Bug fix

• fix: adapt to rusqlite 0.29 and tighten dependency requirements for rusqlite (see this discussion)

Version 1.0.1

Bug Fix

• fix: error instead of panicking on higher migration level (see commit ad57d92d1677420eb81c4e25635be1884f9b7ce7)

Other

• Documentation improvements

Version 1.0.0

Breaking changes

• Remove deprecated symbols (Migrations.latest, SchemaVersionError::MigrateToLowerNotSupported)

Other

• Documentation improvements

Version 0.5.1

Potentially Breaking Changes

• Update the rusqlite crate (to protect agaisnt RUSTSEC-2020-0014)

Other

• Improve the documentation

Version 0.5.0

• Update the env_logger dependency
• Improve the documentation

Version 0.4.1 / 0.4.2

• Update documentation

Version 0.4.0

New features

• Add downward migrations, i.e. migrations to go to past schema version of the database. Thanks @MightyPork!
• Unsafe code is now forbidden.

Breaking changes

• Rename latest to to_latest. The old symbol is deprecated and will be removed eventually.
• An error is now returned when a migration is attempted while no migrations exist.

Other

• Improve general rust API documentation.
• Generate parts of the readme based on rust comments, for increased consistency with the docs.rs content.
• Various refactoring and clean-ups.

Version 0.3.1

Fix in readme, for crates.io

Version 0.3

New features

• Multi line sql statements like:

  M::up(r#"
  CREATE TABLE t1(a, b);
  CREATE TABLE t2(a, b);
  "#)
  

  are now fully supported

Other

• Various doc & CI improvements
• Fix a case of failure with silent errors.

⚡ TL;DR

Open cargo info in Vim or neovim for the package under the cursor using these 4 lines of Lua.

Cargo info

Rust 1.82 was released a couple of days ago. It’s packed with improvements, but one in particular caught my eye. Cargo now has a info sub-command. It displays details about a package in the registry from the comfort of your terminal. Here is an example:

$ cargo info lazy_static
lazy_static #macro #lazy #static
A macro for declaring lazily evaluated statics in Rust.
version: 1.5.0
license: MIT OR Apache-2.0
rust-version: unknown
documentation: https://docs.rs/lazy_static
repository: https://github.com/rust-lang-nursery/lazy-static.rs
crates.io: https://crates.io/crates/lazy_static/1.5.0
features:
  spin        = [dep:spin]
  spin_no_std = [spin]
note: to see how you depend on lazy_static, run `cargo tree --invert --package lazy_static@1.5.0`

Vim and neovim generally composes well with other terminal tools. So how can we easily integrate cargo info and neovim?

Demo

The goal is to press a key and display the cargo info for the crate under the cursor in a Cargo.toml file. Like this:

Introducing keywordprg

In the above demonstration, we press K over a crates name. Then neovim executes the program set in keywordprg, appending the work under the cursor. So if the cursor is on lazy_static

[dev-dependencies]
iai = "0.1"
insta = "1.40.0"
lazy_static = "1.5.0"
#   ^ cursor is here when we press K
mktemp = "0.5"

and keywordprg is set to cargo info, the command cargo info lazy_static is executed in a new terminal.

We can further improve this. Since we want a fast answer (without checking the remote repository), let’s use cargo info --offline. And we would like pretty colors, let’s force that using --color=always.

We only want to alter keywordprg when a Cargo.toml file is edited, because it makes no sense to call cargo info in a Python file. We can use a ftplugin for toml files for that¹, so that the plugin is only loaded and executed when a toml file is executed. Furthermore we can change the setting only when opening a file named “Cargo.toml”, instead of changing it for every toml file. We can put the necessary configuration in ~/.config/nvim/ftplugin/toml.lua², like so:

if vim.endswith(vim.fn.bufname(), "Cargo.toml") then
  vim.opt_local.keywordprg = "cargo info --color=always --offline"
end

-- Add chars that are often part of keys, especially in rust crates
-- (https://toml.io/en/v1.0.0#keys)
vim.opt_local.iskeyword:append "-"

The Lua code above also changes the iskeyword preference. This is so that tokio-test is considered as one word (a “keyword” in Vim parlance), instead of two (tokio and test). With this set, doing K on tokio-test will behave properly, because tokio-test is passed to the command, instead of just tokio.

One final note: the above configuration was the only thing sourced in the demo. All the rest is default, vanilla, neovim 0.10.2. And this does not even require recent neovim features, it has been supported in Vim for many years.

Learnings

Obviously this could be further refined. Other options could be passed to cargo info, like -v to make it more verbose and list dependencies. Some more scripting could add useful features to further improve the integration. For this particular problem, there are even a full plugin with many more features. But the point is to showcase a simple and robust integration³, applicable in a wide variety of contexts. In particular when the use case is too niche, a full plugin is too costly to write and maintain for the benefits it provides.

Let’s highlight the takeaways from this post that are applicable in a wide variety of contexts.

First, a number of Neovim commands can do something with the keyword under the cursor. Adjusting what counts as a keyword boundary is often, but not always, done in the syntax file of a particular language. Or you may just want to make a different trade off and set your own iskeyword value.

Second, the K mapping is often used to look up a word in a documentation (it is set to open man pages by default). It even works in visual mode, looking up the selected text. And arbitrary Vim or shell commands can be used, instead of the default :Man.

Please do read the corresponding parts of the Vim manual linked in this section to learn more. Next time, you may come up with your own quick integration between Vim and another tool. Happy hacking!

⚡ TL;DR

The Default trait can enhance the maintainability of your code. Default values for common types are listed at the end.

A PR Review

Recently, while reviewing a PR¹, I noticed that part of the patch was introducing a new field to a struct:

 1diff --git a/src/lib.rs b/src/lib.rs
 2index eba9a3a..8619e06 100644
 3--- a/src/lib.rs
 4+++ b/src/lib.rs
 5@@ -106,8 +108,9 @@ use std::{
 6 #[derive(Debug, PartialEq, Clone)]
 7 pub struct M<'u> {
 8     up: &'u str,
 9     down: Option<&'u str>,
10+    foreign_key_check: bool,
11 }
12 
13 impl<'u> M<'u> {
14@@ -137,8 +140,9 @@ impl<'u> M<'u> {
15     pub const fn up(sql: &'u str) -> Self {
16         Self {
17             up: sql,
18             down: None,
19+            foreign_key_check: false,
20         }
21     }

That prompted me to reflect on the code I had initially written. Prior to the patch, it looked roughly² like this:

 1#[derive(Debug, PartialEq, Clone)]
 2pub struct M<'u> {
 3    up: &'u str,
 4    down: Option<&'u str>,
 5}
 6
 7impl<'u> M<'u> {
 8    pub const fn up(sql: &'u str) -> Self {
 9        Self {
10            up: sql,
11            down: None,
12        }
13    }
14}

The Default Trait

What if I had used the Default trait here? The code could have looked like this:

 1#[derive(Debug, Default, PartialEq, Clone)]
 2pub struct M<'u> {
 3    up: &'u str,
 4    down: Option<&'u str>,
 5}
 6
 7impl<'u> M<'u> {
 8    pub const fn up(sql: &'u str) -> Self {
 9        Self {
10            up: sql,
11            ..Default::default()
12        }
13    }
14}

On the first line, the #[derive(Default)] attribute makes the structure M implement the Default trait. Thanks to this trait, a call to M::default() will create a struct with default values for its fields: M { up: "", down: None }. Note that when a structure M is expected, Default::default() is equivalent to M::default().

We then need to initialize the two fields of that structure, overriding some defaults:

• up is defined directly as before. That’s the value we want to override.
• down is set by the Default trait. This is done by ..Default::default() on line 11. Default::default() provides the values. Then the .. syntax fills out the fields that were not directly set. down is thus set to the same value as before, None.

The code is just as long as before, when we were not using the Default trait. But then, line 19 of the above patch would have been unnecessary: false is the default for a bool, so the new foreign_key_check field would have been covered by the ..Default::default().

This results in a shorter patch:

 1diff --git a/src/lib.rs b/src/lib.rs
 2index eba9a3a..8619e06 100644
 3--- a/src/lib.rs
 4+++ b/src/lib.rs
 5@@ -106,8 +108,9 @@ use std::{
 6 #[derive(Debug, PartialEq, Clone)]
 7 pub struct M<'u> {
 8     up: &'u str,
 9     down: Option<&'u str>,
10+    foreign_key_check: bool,
11 }
12 
13 impl<'u> M<'u> {

Conclusion

In the example of this post, we are doing only one instantiation of that particular struct, and it has very few fields anyway. But if there were many instantiations of that struct, we would have had to change all of those. Then, using Default would have been quite beneficial.

This pattern were the return type is built with a call to Default::default() seems relatively common in the Rust organization. It can enhance maintainability, much more than I initially thought.

Of course this is a balancing act. For instance, this pattern could be abused by defining custom default values on primitive types for a particular structure. That would lead to Default::default() filling surprising values and the code would be less predictable.

Appendix: Defaults for Some Common Types With derive

Why did I not use the Default trait initially? Part of it might be the fear of introducing incorrect code. It was slightly unclear to me what derive uses as a default value for common primitive types. And you don’t want a field set explicitly to false becoming a true once you use Default, right?

Let’s take a closer look by running the following program:

#[derive(Debug, Default)]
struct D<'a> {
    b: bool,
    c: char,
    o: Option<usize>,

    string: String,
    str: &'a str,

    v: Vec<usize>,
    a: [usize; 10],
    s: &'a [u32],

    f: f64,
    u: (usize, u32, u64)
}

fn main() {
    println!("{:#?}", D::default());
}

Output:

D {
    b: false,
    c: '\0',
    o: None,
    string: "",
    str: "",
    v: [],
    a: [
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
    ],
    s: [],
    f: 0.0,
    u: (
        0,
        0,
        0,
    ),
}

It turns out that in general, the default for common types in the standard library is a 0 byte in the underlying data structure. Note that arrays are fixed size in rust and thus the default is an array of the right size, filled with defaults for the inner type. That’s quite similar to go.

Quick Reference

Here is a table for future reference:

Rusqlite Migration is a performant and simple schema migration library for rusqlite.

• Performance:
  • Fast database opening: to keep track of the current migration state, most tools create one or more tables in the database. These tables require parsing by SQLite and are queried with SQL statements. This library uses the user_version value instead. It’s much lighter as it is just an integer at a fixed offset in the SQLite file.
  • Fast compilation: this crate is very small and does not use macros to define the migrations.
• Simplicity: this crate strives for simplicity. Just define a set of SQL statements as strings in your Rust code. Add more SQL statements over time as needed. No external CLI required. Additionally, rusqlite_migration works especially well with other small libraries complementing rusqlite, like serde_rusqlite.

Example

Here, we define SQL statements to run with Migrations::new() and run these (if necessary) with Migrations::to_latest().

use rusqlite::{params, Connection};
use rusqlite_migration::{Migrations, M};

// 1️⃣ Define migrations
const MIGRATIONS_SLICE: &[M<'_>] = &[
    M::up("CREATE TABLE friend(name TEXT NOT NULL);"),
    // In the future, add more migrations here:
    //M::up("ALTER TABLE friend ADD COLUMN email TEXT;"),
];
const MIGRATIONS: Migrations<'_> = Migrations::from_slice(MIGRATIONS_SLICE);

fn main() {
    let mut conn = Connection::open_in_memory().unwrap();

    // Apply some PRAGMA, often better to do it outside of migrations
    conn.pragma_update_and_check(None, "journal_mode", &"WAL", |_| Ok(()))
        .unwrap();

    // 2️⃣ Update the database schema, atomically
    MIGRATIONS.to_latest(&mut conn).unwrap();

    // 3️⃣ Use the database 🥳
    conn.execute("INSERT INTO friend (name) VALUES (?1)", params!["John"])
        .unwrap();
}

Please see the examples folder for more, in particular:

• migrations with multiple SQL statements (using for instance r#"…" or include_str!(…))
• migrations defined from a directory with SQL files
• migrations to previous versions (downward migrations)
• migrations when using async

I’ve also made a cheatsheet of SQLite pragma for improved performance and consistency.

Built-in tests

To test that the migrations are working, you can add this in your test module:

#[test]
fn migrations_test() {
    assert!(MIGRATIONS.validate().is_ok());
}

The migrations object is also suitable for serialisation with insta, using the Debug serialisation. You can store a snapshot of your migrations like this:

#[test]
fn migrations_insta_snapshot() {
    let migrations = Migrations::new(vec![
        // ...
    ]);
    insta::assert_debug_snapshot!(migrations);
}

Optional Features

Rusqlite migration provides several Cargo features. They are:

• from-directory: enable loading migrations from *.sql files in a given directory

Active Users

This crate is actively used in a number of projects. You can find up-to-date list of those on:

• crates.io / lib.rs
• GitHub’s list of dependent repositories

A number of contributors are also reporting issues as they arise, another indicator of active use.

Minimum Supported Rust Version (MSRV)

This crate extends rusqlite and as such is tightly integrated with it. Thus, it supports the same MSRV as rusqlite. At the time of writing, this means:

Limits

1. Since this crate uses the user_version field, if your program or any other library changes it, this library will behave in an unspecified way: it may return an error, apply the wrong set of migrations, do nothing at all…

2. The user_version field is effectively a i32, so there is a theoretical limit (about two billion) on the number of migrations that can be applied by this library. You are likely to hit memory limits well before that though, so in practice, you can think of the number of migrations as limitless. And you would need to create 10 000 new migrations, every day, for over 5 centuries, before getting close to the limit.

Contributing

Contributions (documentation or code improvements in particular) are welcome, see contributing!

We use various tools for testing that you may find helpful to install locally (e.g. to fix failing CI checks):

• cargo-insta
• cargo-mutants

Acknowledgments

I would like to thank all the contributors, as well as the authors of the dependencies this crate uses.

Thanks to Migadu for offering a discounted service to support this project. It is not an endorsement by Migadu though.

Getting started

Install the latest version:

$ cargo install sesters

Exemple of plain text conversion:

$ sesters convert a price burried 1 USD in text
USD 1.00 ➜ EUR 0.89
$ sesters convert -- -1 €
EUR -1.00 ➜ USD -1.10
$ sesters convert
I can type and press enter EUR 2356
EUR 2345.00 ➜ USD 2586.53

It is then visible in the history:

$ sesters history list
╔═══╦═══════════════════════════════════╦═════════════════════════════════════╦═══════════════════════════╗
║ 1 ║ 2021-10-09 22:36:54.733991464 UTC ║ a price burried 1 USD in text       ║ USD 1.00 ➜ EUR 0.86       ║
╠═══╬═══════════════════════════════════╬═════════════════════════════════════╬═══════════════════════════╣
║ 2 ║ 2021-10-09 22:36:58.147102167 UTC ║ -1 €                                ║ EUR -1.00 ➜ USD -1.16     ║
╠═══╬═══════════════════════════════════╬═════════════════════════════════════╬═══════════════════════════╣
║ 3 ║ 2021-10-09 22:37:06.656527072 UTC ║ I can type and press enter EUR 2356 ║ EUR 2356.00 ➜ USD 2727.15 ║
╚═══╩═══════════════════════════════════╩═════════════════════════════════════╩═══════════════════════════╝

Features

• Find prices in plain text with several currencies
• Store exchange rates locally for a while, to speed up future conversions
• Save recent conversion history. The history is automatically deleted after a while

About the name

Inspired by this coin.

By Classical Numismatic Group, Inc. http://www.cngcoins.com, CC BY-SA 3.0, Link

Contribute

Contributions are welcome, see this document!

Licence

Sesters is licensed under GNU General Public License Version 3 or later.