From afb6b1066e61f8e3875f530d96cfb5a299f13fda Mon Sep 17 00:00:00 2001 From: Jonathan Newnham Date: Tue, 11 Jul 2023 09:36:05 +1200 Subject: [PATCH] improve docs about migration files (#2566) --- sqlx-core/src/migrate/source.rs | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/sqlx-core/src/migrate/source.rs b/sqlx-core/src/migrate/source.rs index 10a18b365b..dd6d36afcc 100644 --- a/sqlx-core/src/migrate/source.rs +++ b/sqlx-core/src/migrate/source.rs @@ -7,16 +7,24 @@ use std::borrow::Cow; use std::fmt::Debug; use std::path::{Path, PathBuf}; +/// In the default implementation, a MigrationSource is a directory which +/// contains the migration SQL scripts. All these scripts must be stored in +/// files with names using the format `_.sql`, where +/// `` is a string that can be parsed into `i64` and its value is +/// greater than zero, and `` is a string. +/// +/// Files that don't match this format are silently ignored. +/// +/// You can create a new empty migration script using sqlx-cli: +/// `sqlx migrate add `. +/// +/// Note that migrations for each database are tracked using the +/// `_sqlx_migrations` table (stored in the database). If a migration's hash +/// changes and it has already been run, this will cause an error. pub trait MigrationSource<'s>: Debug { fn resolve(self) -> BoxFuture<'s, Result, BoxDynError>>; } -/// Implementation of the `MigrationSource` for [std::path::Path]. -/// -/// The path has to point to a directory, which contains the migration SQL scripts. All these -/// scripts must be stored in files with names using the format `_.sql`, -/// where `` is a string that can be parsed into `i64` and its value is greater than zero, -/// and `` is a string. impl<'s> MigrationSource<'s> for &'s Path { fn resolve(self) -> BoxFuture<'s, Result, BoxDynError>> { Box::pin(async move {