surrealdb_migrate/
lib.rs

1//! A lib to migrate a [SurrealDB] programmatically from within an application
2//! or to build a custom migration tool.
3//!
4//! ## Usage
5//!
6//! For migrating or reverting a database the easiest way is to configure a
7//! [`MigrationRunner`] and use its functions [`MigrationRunner::migrate()`]
8//! and [`MigrationRunner::revert()`].
9//!
10//! ### Example
11//!
12//! ```no_run
13//! use std::path::Path;
14//! use anyhow::Context;
15//! use surrealdb_migrate::{
16//!     config::{DbAuthLevel, DbClientConfig, RunnerConfig},
17//!     runner::MigrationRunner,
18//!     db_client::connect_to_database
19//! };
20//!
21//! #[tokio::main]
22//! async fn main() -> Result<(), anyhow::Error> {
23//!     // setup database connection
24//!     let db_config = DbClientConfig::default()
25//!         .with_address("wss://localhost:9000")
26//!         .with_namespace("playground")
27//!         .with_database("examples")
28//!         .with_auth_level(DbAuthLevel::Database)
29//!         .with_username("example.user")
30//!         .with_password("s3cr3t");
31//!     let db = connect_to_database(&db_config)
32//!         .await
33//!         .context("failed to connect to examples database")?;
34//!
35//!     // Instantiate the `MigrationRunner`
36//!     let runner_config = RunnerConfig::default()
37//!         .with_migrations_folder(Path::new("my_application/migrations"));
38//!     let runner = MigrationRunner::new(runner_config);
39//!
40//!     // Run all forward (up) migrations
41//!     runner.migrate(&db).await?;
42//!
43//!     Ok(())
44//! }
45//! ```
46//!
47//! For a fully working example see the [run_migrations] example.
48//!
49//! The configuration of the database connection and the migration runner can be
50//! provided in an application specific way or by using the configuration
51//! mechanism provided by this crate (see next chapter below).
52//!
53//! ## Configuring the DB-connection and the Migration-Runner
54//!
55//! Both the DB-connection and the [`MigrationRunner`] can be configured using
56//! the configuration mechanism provided by this crate. The configuration
57//! mechanism is gated behind the optional crate feature `config`.
58//!
59//! This mechanism loads the configuration settings from the configuration file
60//! `surrealdb-migrate.toml` and from environment variables.
61//! See the [`settings`] module for more details.
62//!
63//! ## Crate features
64//!
65//! | Feature  | Description                                                                                                 | Default |
66//! |----------|-------------------------------------------------------------------------------------------------------------|:-------:|
67//! | `config` | Provides a configuration mechanism for the DB-connection and the migration runner (see [`settings`] module) | no      |
68//!
69//! [run_migrations]: https://github.com/innoave/surrealdb-migrate/blob/main/surrealdb-migrate/examples/run_migrations.rs
70//! [SurrealDB]: https://surrealdb.com
71#![doc(html_root_url = "https://docs.rs/surrealdb-migrate/0.2.0")]
72
73// imports for crate level doc
74#[allow(unused_imports)]
75use runner::MigrationRunner;
76
77pub mod runner;
78
79//
80// re-export other crates of this project for a one-crate-dependency experience
81// for users of this crate.
82//
83
84#[doc(inline)]
85pub use database_migration::*;
86#[doc(inline)]
87pub use database_migration_files as files;
88#[doc(inline)]
89#[cfg(feature = "config")]
90pub use surrealdb_migrate_config as settings;
91pub mod db_client {
92    #[doc(inline)]
93    pub use surrealdb_migrate_db_client::DbConnection;
94    #[doc(inline)]
95    pub use surrealdb_migrate_db_client::DbError;
96    #[doc(inline)]
97    pub use surrealdb_migrate_db_client::connect_to_database;
98}
99
100// test code snippets in the README.md
101#[cfg(doctest)]
102#[doc = include_str!("../../README.md")]
103#[allow(dead_code)]
104type TestExamplesInReadme = ();
105
106// workaround for false positive 'unused extern crate' warnings until
107// Rust issue [#95513](https://github.com/rust-lang/rust/issues/95513) is fixed
108#[cfg(test)]
109mod dummy_extern_uses {
110    use anyhow as _;
111    use assert_fs as _;
112    use color_eyre as _;
113    use dotenvy as _;
114    use testcontainers_modules as _;
115    use tokio as _;
116    use version_sync as _;
117}
surrealdb_migrate/lib.rs

surrealdb_migrate/
lib.rs
