migrations_macros/
lib.rs

Help
1// Built-in Lints
2// Clippy lints
3#![allow(
4    clippy::map_unwrap_or,
5    clippy::match_same_arms,
6    clippy::type_complexity,
7    clippy::needless_doctest_main
8)]
9#![warn(
10    clippy::unwrap_used,
11    clippy::print_stdout,
12    clippy::mut_mut,
13    clippy::non_ascii_literal,
14    clippy::similar_names,
15    clippy::unicode_not_nfc,
16    clippy::enum_glob_use,
17    clippy::if_not_else,
18    clippy::items_after_statements,
19    clippy::used_underscore_binding,
20    missing_debug_implementations,
21    missing_copy_implementations
22)]
23#![cfg_attr(test, allow(clippy::unwrap_used))]
24extern crate proc_macro;
25
26mod embed_migrations;
27mod migrations;
28
29use proc_macro::TokenStream;
30
31/// This macro will read your migrations at compile time, and create a constant value containing
32/// an embedded list of all your migrations as available at compile time.
33/// This is useful if you would like to use Diesel's migration infrastructure, but want to ship a single executable
34/// file (such as for embedded applications). It can also be used to apply migrations to an in
35/// memory database (Diesel does this for its own test suite).
36///
37/// You can optionally pass the path to the migrations directory to this macro. When left
38/// unspecified, Diesel will search for the migrations directory in the same way that
39/// Diesel CLI does. If specified, the path should be relative to the directory where `Cargo.toml`
40/// resides.
41///
42/// # Examples
43///
44/// ```rust
45/// use diesel_migrations::{embed_migrations, EmbeddedMigrations, MigrationHarness};
46/// # use std::error::Error;
47/// # include!("../../../diesel/src/doctest_setup.rs");
48/// #
49/// # #[cfg(feature = "postgres")]
50/// # fn migration_connection() -> diesel::PgConnection {
51/// #    let connection_url = database_url_from_env("PG_DATABASE_URL");
52/// #    let mut conn = diesel::PgConnection::establish(&connection_url).unwrap();
53/// #    conn.begin_test_transaction().unwrap();
54/// #    conn
55/// # }
56/// #
57/// # #[cfg(feature = "sqlite")]
58/// # fn migration_connection() -> diesel::SqliteConnection {
59/// #    let connection_url = database_url_from_env("SQLITE_DATABASE_URL");
60/// #    let mut conn = diesel::SqliteConnection::establish(&connection_url).unwrap();
61/// #    conn.begin_test_transaction().unwrap();
62/// #    conn
63/// # }
64/// #
65/// # #[cfg(feature = "mysql")]
66/// # fn migration_connection() -> diesel::MysqlConnection {
67/// #    let connection_url = database_url_from_env("MYSQL_DATABASE_URL");
68/// #    let mut conn = diesel::MysqlConnection::establish(&connection_url).unwrap();
69/// #    conn
70/// # }
71/// #
72/// #
73/// # #[cfg(feature = "postgres")]
74/// pub const MIGRATIONS: EmbeddedMigrations = embed_migrations!("../../migrations/postgresql");
75/// # #[cfg(all(feature = "mysql", not(feature = "postgres")))]
76/// # pub const MIGRATIONS: EmbeddedMigrations = embed_migrations!("../../migrations/mysql");
77/// # #[cfg(all(feature = "sqlite", not(any(feature = "postgres", feature = "mysql"))))]
78/// # pub const MIGRATIONS: EmbeddedMigrations = embed_migrations!("../../migrations/sqlite");
79///
80/// # fn main() {
81/// #     let connection = &mut migration_connection();
82/// #     run_migrations(connection).unwrap();
83/// # }
84///
85/// fn run_migrations(connection: &mut impl MigrationHarness<DB>) -> Result<(), Box<dyn Error + Send + Sync + 'static>> {
86/// #   #[cfg(feature = "mysql")]
87/// #   connection.revert_all_migrations(MIGRATIONS)?;
88///
89///     // This will run the necessary migrations.
90///     //
91///     // See the documentation for `MigrationHarness` for
92///     // all available methods.
93///     connection.run_pending_migrations(MIGRATIONS)?;
94///
95///     Ok(())
96/// }
97/// ```
98///
99/// # Automatic rebuilds
100///
101/// Due to limitations in rusts proc-macro API there is currently no
102/// way to signal that a specific proc macro should be rerun if some
103/// external file changes/is added. This implies that `embed_migrations!`
104/// cannot regenerate the list of embedded migrations if **only** the
105/// migrations are changed. This limitation can be solved by adding a
106/// custom `build.rs` file to your crate, such that the crate is rebuild
107/// if the migration directory changes.
108///
109/// Add the following `build.rs` file to your project to fix the problem
110///
111/// ```
112/// fn main() {
113///    println!("cargo:rerun-if-changed=path/to/your/migration/dir/relative/to/your/Cargo.toml");
114/// }
115/// ```
116#[proc_macro]
117pub fn embed_migrations(input: TokenStream) -> TokenStream {
118    embed_migrations::expand(input.to_string())
119        .to_string()
120        .parse()
121        .expect("Failed to create embedded migrations instance")
122}
migrations_macros/lib.rs

migrations_macros/
lib.rs
