diesel_migrations/
file_based_migrations.rs

Help
1use std::fmt::Display;
2use std::fs::{DirEntry, File};
3use std::io::Read;
4use std::path::{Path, PathBuf};
5
6use diesel::backend::Backend;
7use diesel::connection::BoxableConnection;
8use diesel::migration::{
9    self, Migration, MigrationMetadata, MigrationName, MigrationSource, MigrationVersion,
10};
11use migrations_internals::TomlMetadata;
12
13use crate::errors::{MigrationError, RunMigrationsError};
14
15/// A migration source based on a migration directory in the file system
16///
17/// A valid migration directory contains a sub folder per migration.
18/// Each migration folder contains a `up.sql` file containing the migration itself
19/// and a `down.sql` file containing the necessary SQL to revert the migration.
20/// Additionally each folder can contain a `metadata.toml` file controlling how the
21/// individual migration should be handled by the migration harness.
22///
23/// To embed an existing migration folder into the final binary see
24/// [`embed_migrations!`](crate::embed_migrations!).
25///
26/// ## Example
27///
28/// ```text
29/// # Directory Structure
30/// - 20151219180527_create_users
31///     - up.sql
32///     - down.sql
33/// - 20160107082941_create_posts
34///     - up.sql
35///     - down.sql
36///     - metadata.toml
37/// ```
38///
39/// ```sql
40/// -- 20151219180527_create_users/up.sql
41/// CREATE TABLE users (
42///   id SERIAL PRIMARY KEY,
43///   name VARCHAR NOT NULL,
44///   hair_color VARCHAR
45/// );
46/// ```
47///
48/// ```sql
49/// -- 20151219180527_create_users/down.sql
50/// DROP TABLE users;
51/// ```
52///
53/// ```sql
54/// -- 20160107082941_create_posts/up.sql
55/// CREATE TABLE posts (
56///   id SERIAL PRIMARY KEY,
57///   user_id INTEGER NOT NULL,
58///   title VARCHAR NOT NULL,
59///   body TEXT
60/// );
61/// ```
62///
63/// ```sql
64/// -- 20160107082941_create_posts/down.sql
65/// DROP TABLE posts;
66/// ```
67///
68/// ```toml
69/// ## 20160107082941_create_posts/metadata.toml
70///
71/// ## specifies if a migration is executed inside a
72/// ## transaction or not. This configuration is optional
73/// ## by default all migrations are run in transactions.
74/// ##
75/// ## For certain types of migrations, like creating an
76/// ## index onto a existing column, it is required
77/// ## to set this to false
78/// run_in_transaction = true
79/// ```
80#[derive(Clone)]
81pub struct FileBasedMigrations {
82    base_path: PathBuf,
83}
84
85impl FileBasedMigrations {
86    /// Create a new file based migration source based on a specific path
87    ///
88    /// This methods fails if the path passed as argument is no valid migration directory
89    pub fn from_path(path: impl AsRef<Path>) -> Result<Self, MigrationError> {
90        for dir in migrations_directories(path.as_ref())? {
91            let path = dir?.path();
92            if !migrations_internals::valid_sql_migration_directory(&path) {
93                return Err(MigrationError::UnknownMigrationFormat(path));
94            }
95        }
96        Ok(Self {
97            base_path: path.as_ref().to_path_buf(),
98        })
99    }
100
101    /// Create a new file based migration source by searching the migration diretcory
102    ///
103    /// This method looks in the current and all parent directories for a folder named
104    /// `migrations`
105    ///
106    /// This method fails if no valid migration directory is found
107    pub fn find_migrations_directory() -> Result<Self, MigrationError> {
108        Self::find_migrations_directory_in_path(std::env::current_dir()?.as_path())
109    }
110
111    /// Create a new file based migration source by searching a give path for the migration
112    /// directory
113    ///
114    /// This method looks in the passed directory and all parent directories for a folder
115    /// named `migrations`
116    ///
117    /// This method fails if no valid migration directory is found
118    pub fn find_migrations_directory_in_path(
119        path: impl AsRef<Path>,
120    ) -> Result<Self, MigrationError> {
121        let migrations_directory = search_for_migrations_directory(path.as_ref())?;
122        Self::from_path(migrations_directory.as_path())
123    }
124
125    #[doc(hidden)]
126    pub fn path(&self) -> &Path {
127        &self.base_path
128    }
129}
130
131fn search_for_migrations_directory(path: &Path) -> Result<PathBuf, MigrationError> {
132    migrations_internals::search_for_migrations_directory(path)
133        .ok_or_else(|| MigrationError::MigrationDirectoryNotFound(path.to_path_buf()))
134}
135
136fn migrations_directories(
137    path: &'_ Path,
138) -> Result<impl Iterator<Item = Result<DirEntry, MigrationError>> + '_, MigrationError> {
139    Ok(migrations_internals::migrations_directories(path)?.map(move |e| e.map_err(Into::into)))
140}
141
142fn migrations_in_directory(
143    path: &'_ Path,
144) -> Result<impl Iterator<Item = Result<SqlFileMigration, MigrationError>> + '_, MigrationError> {
145    Ok(migrations_directories(path)?.map(|entry| SqlFileMigration::from_path(&entry?.path())))
146}
147
148impl<DB: Backend> MigrationSource<DB> for FileBasedMigrations {
149    fn migrations(&self) -> migration::Result<Vec<Box<dyn Migration<DB>>>> {
150        migrations_in_directory(&self.base_path)?
151            .map(|r| Ok(Box::new(r?) as Box<dyn Migration<DB>>))
152            .collect()
153    }
154}
155
156struct SqlFileMigration {
157    base_path: PathBuf,
158    metadata: TomlMetadataWrapper,
159    name: DieselMigrationName,
160}
161
162impl SqlFileMigration {
163    fn from_path(path: &Path) -> Result<Self, MigrationError> {
164        if migrations_internals::valid_sql_migration_directory(path) {
165            let metadata = TomlMetadataWrapper(
166                TomlMetadata::read_from_file(&path.join("metadata.toml")).unwrap_or_default(),
167            );
168            Ok(Self {
169                base_path: path.to_path_buf(),
170                metadata,
171                name: DieselMigrationName::from_path(path)?,
172            })
173        } else {
174            Err(MigrationError::UnknownMigrationFormat(path.to_path_buf()))
175        }
176    }
177}
178
179impl<DB: Backend> Migration<DB> for SqlFileMigration {
180    fn run(&self, conn: &mut dyn BoxableConnection<DB>) -> migration::Result<()> {
181        Ok(run_sql_from_file(
182            conn,
183            &self.base_path.join("up.sql"),
184            &self.name,
185        )?)
186    }
187
188    fn revert(&self, conn: &mut dyn BoxableConnection<DB>) -> migration::Result<()> {
189        let down_path = self.base_path.join("down.sql");
190        if matches!(down_path.metadata(), Err(e) if e.kind() == std::io::ErrorKind::NotFound) {
191            Err(MigrationError::NoMigrationRevertFile.into())
192        } else {
193            Ok(run_sql_from_file(conn, &down_path, &self.name)?)
194        }
195    }
196
197    fn metadata(&self) -> &dyn MigrationMetadata {
198        &self.metadata
199    }
200
201    fn name(&self) -> &dyn MigrationName {
202        &self.name
203    }
204}
205
206#[derive(Debug, PartialEq, Eq)]
207pub struct DieselMigrationName {
208    name: String,
209    version: MigrationVersion<'static>,
210}
211
212impl Clone for DieselMigrationName {
213    fn clone(&self) -> Self {
214        Self {
215            name: self.name.clone(),
216            version: self.version.as_owned(),
217        }
218    }
219}
220
221impl DieselMigrationName {
222    fn from_path(path: &Path) -> Result<Self, MigrationError> {
223        let name = path
224            .file_name()
225            .ok_or_else(|| MigrationError::UnknownMigrationFormat(path.to_path_buf()))?
226            .to_string_lossy();
227        Self::from_name(&name)
228    }
229
230    pub(crate) fn from_name(name: &str) -> Result<Self, MigrationError> {
231        let version = migrations_internals::version_from_string(name)
232            .ok_or_else(|| MigrationError::UnknownMigrationFormat(PathBuf::from(name)))?;
233        Ok(Self {
234            name: name.to_owned(),
235            version: MigrationVersion::from(version),
236        })
237    }
238}
239
240impl MigrationName for DieselMigrationName {
241    fn version(&self) -> MigrationVersion {
242        self.version.as_owned()
243    }
244}
245
246impl Display for DieselMigrationName {
247    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
248        write!(f, "{}", self.name)
249    }
250}
251
252#[derive(Default)]
253#[doc(hidden)]
254pub struct TomlMetadataWrapper(TomlMetadata);
255
256impl TomlMetadataWrapper {
257    #[doc(hidden)]
258    pub const fn new(run_in_transaction: bool) -> Self {
259        Self(TomlMetadata::new(run_in_transaction))
260    }
261}
262
263impl MigrationMetadata for TomlMetadataWrapper {
264    fn run_in_transaction(&self) -> bool {
265        self.0.run_in_transaction
266    }
267}
268
269fn run_sql_from_file<DB: Backend>(
270    conn: &mut dyn BoxableConnection<DB>,
271    path: &Path,
272    name: &DieselMigrationName,
273) -> Result<(), RunMigrationsError> {
274    let map_io_err = |e| RunMigrationsError::MigrationError(name.clone(), MigrationError::from(e));
275
276    let mut sql = String::new();
277    let mut file = File::open(path).map_err(map_io_err)?;
278    file.read_to_string(&mut sql).map_err(map_io_err)?;
279
280    if sql.is_empty() {
281        return Err(RunMigrationsError::EmptyMigration(name.clone()));
282    }
283
284    conn.batch_execute(&sql)
285        .map_err(|e| RunMigrationsError::QueryError(name.clone(), e))?;
286    Ok(())
287}
288
289#[cfg(test)]
290mod tests {
291    extern crate tempfile;
292
293    use super::*;
294
295    use self::tempfile::Builder;
296    use std::fs;
297
298    #[test]
299    fn migration_directory_not_found_if_no_migration_dir_exists() {
300        let dir = Builder::new().prefix("diesel").tempdir().unwrap();
301
302        assert_eq!(
303            Err(MigrationError::MigrationDirectoryNotFound(
304                dir.path().into()
305            )),
306            search_for_migrations_directory(dir.path())
307        );
308    }
309
310    #[test]
311    fn migration_directory_defaults_to_pwd_slash_migrations() {
312        let dir = Builder::new().prefix("diesel").tempdir().unwrap();
313        let temp_path = dir.path().canonicalize().unwrap();
314        let migrations_path = temp_path.join("migrations");
315
316        fs::create_dir(&migrations_path).unwrap();
317
318        assert_eq!(
319            Ok(migrations_path),
320            search_for_migrations_directory(&temp_path)
321        );
322    }
323
324    #[test]
325    fn migration_directory_checks_parents() {
326        let dir = Builder::new().prefix("diesel").tempdir().unwrap();
327        let temp_path = dir.path().canonicalize().unwrap();
328        let migrations_path = temp_path.join("migrations");
329        let child_path = temp_path.join("child");
330
331        fs::create_dir(&child_path).unwrap();
332        fs::create_dir(&migrations_path).unwrap();
333
334        assert_eq!(
335            Ok(migrations_path),
336            search_for_migrations_directory(&child_path)
337        );
338    }
339
340    #[test]
341    fn migration_paths_in_directory_ignores_files() {
342        let dir = Builder::new().prefix("diesel").tempdir().unwrap();
343        let temp_path = dir.path().canonicalize().unwrap();
344        let migrations_path = temp_path.join("migrations");
345        let file_path = migrations_path.join("README.md");
346
347        fs::create_dir(migrations_path.as_path()).unwrap();
348        fs::File::create(file_path.as_path()).unwrap();
349
350        let migrations = migrations_in_directory(&migrations_path)
351            .unwrap()
352            .collect::<Result<Vec<_>, _>>()
353            .unwrap();
354
355        assert_eq!(0, migrations.len());
356    }
357
358    #[test]
359    fn migration_paths_in_directory_ignores_dot_directories() {
360        let dir = Builder::new().prefix("diesel").tempdir().unwrap();
361        let temp_path = dir.path().canonicalize().unwrap();
362        let migrations_path = temp_path.join("migrations");
363        let dot_path = migrations_path.join(".hidden_dir");
364
365        fs::create_dir(migrations_path.as_path()).unwrap();
366        fs::create_dir(dot_path.as_path()).unwrap();
367
368        let migrations = migrations_in_directory(&migrations_path)
369            .unwrap()
370            .collect::<Result<Vec<_>, _>>()
371            .unwrap();
372
373        assert_eq!(0, migrations.len());
374    }
375}
diesel_migrations/file_based_migrations.rs

diesel_migrations/
file_based_migrations.rs
