tern-derive 3.1.6

Derive macros for `tern` migration tooling.
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
99
100
101
102
103
104
105
106
107
108
109
110
111

use syn::{DeriveInput, parse_macro_input};

mod internal;
mod quote;

/// A Rust migration requires a struct called `TernMigration` which derives
/// `Migration`.  This is used in concert with [`MigrationSource`] to finish the
/// implementation of [`Migration`] for it.
///
/// With the macro attribute `no_transaction`, the `Migration` implementation
/// is constructed to not run the migration in a database transaction.
///
/// ## Usage
///
/// ```rust,ignore
/// use tern::Migration;
///
/// /// Then implement `tern::QueryBuilder` for this type.
/// #[derive(Migration)]
/// #[tern(no_transaction)]
/// pub struct TernMigration;
/// ```
///
/// [`MigrationSource`]: crate::MigrationSource
/// [`Migration`]: https://docs.rs/tern/latest/tern/trait.Migration.html
#[proc_macro_derive(Migration, attributes(tern))]
pub fn migration(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
    let input = parse_macro_input!(input as DeriveInput);
    quote::expand_impl_migration(&input)
        .unwrap_or_else(syn::Error::into_compile_error)
        .into()
}

/// `MigrationContext` implements the trait [`MigrationContext`], which is
/// required of a type to be suitable for use in a migration [`Runner`].  A
/// bound of [`MigrationSource`][source-core] exists, which can be satisfied by
/// hand or by using the derive macro provided here, [`MigrationSource`].
/// Custom, dynamic behavior for a migration can be defined for the context,
/// which is available to [`QueryBuilder`].
///
/// The macro exposes one optional macro attribute and one optional field
/// attribute:
///
/// * `table` is the optional macro attribute.  With it enabled, the migration
///   history will be stored in this table, located in the default schema for
///   the database driver, instead of the default table, `_tern_migrations`.
/// * `executor_via` decorates the field holding an [`Executor`], which is
///   required of the type to be a context.  If not specified then it is
///   expected that the type itself implements `Executor`.
///
/// ## Usage
///
/// ```rust,ignore
/// use tern::{SqlxPgExecutor, MigrationContext};
///
/// #[derive(MigrationContext)]
/// #[tern(table = "_my_migration_history")]
/// pub struct MyContext {
///     #[tern(executor_via)]
///     executor: SqlxPgExecutor,
/// }
/// ```
///
/// [`Runner`]: https://docs.rs/tern/latest/tern/struct.Runner.html
/// [`QueryBuilder`]: https://docs.rs/tern/latest/tern/trait.QueryBuilder.html
/// [`MigrationContext`]: https://docs.rs/tern/latest/tern/trait.MigrationContext.html
/// [source-core]: https://docs.rs/tern/latest/tern/trait.MigrationSource.html
/// [`MigrationSource`]: crate::MigrationSource
/// [`Executor`]: https://docs.rs/tern/latest/tern/trait.Executor.html
#[proc_macro_derive(MigrationContext, attributes(tern))]
pub fn migration_context(
    input: proc_macro::TokenStream,
) -> proc_macro::TokenStream {
    let input = parse_macro_input!(input as DeriveInput);
    quote::expand_impl_migration_context(&input)
        .unwrap_or_else(syn::Error::into_compile_error)
        .into()
}

/// `MigrationSource` does the work of collecting all of the migrations, sorting
/// them, unifying SQL and Rust migrations under a common interface by
/// implementing [`Migration`], and then exposing methods to return an ordered
/// subset of them to be used in a given operation.  It has one required
/// attribute and one optional attribute.
///
/// * `source` is a required macro attribute.  It is the location of the
///   migration files relative to the project root (i.e., CARGO_MANIFEST_DIR).
///
/// ## Usage
///
/// ```rust,ignore
/// use tern::{SqlxPgExecutor, MigrationSource};
///
/// #[derive(MigrationSource)]
/// #[tern(source = "src/migrations")]
/// pub struct MyContext {
///     #[tern(executor_via)]
///     executor: SqlxPgExecutor,
/// }
/// ```
///
/// [`Migration`]: https://docs.rs/tern/latest/tern/trait.Migration.html
#[proc_macro_derive(MigrationSource, attributes(tern))]
pub fn migration_source(
    input: proc_macro::TokenStream,
) -> proc_macro::TokenStream {
    let input = parse_macro_input!(input as DeriveInput);
    quote::expand_impl_migration_source(&input)
        .unwrap_or_else(syn::Error::into_compile_error)
        .into()
}