1+ /// Configuration for migrations when executed using `sqlx::migrate!()` or through `sqlx-cli`.
2+ ///
3+ /// ### Note
4+ /// A manually constructed [`Migrator`][crate::migrate::Migrator] will not be aware of these
5+ /// configuration options. We recommend using [`sqlx::migrate!()`] instead.
6+ ///
7+ /// ### Warning: Potential Data Loss or Corruption!
8+ /// Many of these options, if changed after migrations are set up,
9+ /// can result in data loss or corruption of a production database
10+ /// if the proper precautions are not taken.
11+ ///
12+ /// Be sure you know what you are doing and to read all relevant documentation _thoroughly_.
13+ #[ derive( Debug , serde:: Deserialize ) ]
14+ pub struct Config {
15+ /// Override the name of the table used to track executed migrations.
16+ ///
17+ /// May be schema-qualified. Defaults to `_sqlx_migrations`.
18+ ///
19+ /// Potentially useful for multi-tenant databases.
20+ ///
21+ /// ### Warning: Potential Data Loss or Corruption!
22+ /// Changing this option for a production database will likely result in data loss or corruption
23+ /// as the migration machinery will no longer be aware of what migrations have been applied
24+ /// and will attempt to re-run them.
25+ ///
26+ /// You should create the new table as a copy of the existing migrations table (with contents!),
27+ /// and be sure all instances of your application have been migrated to the new
28+ /// table before deleting the old one.
29+ ///
30+ /// ### Example
31+ /// `sqlx.toml`:
32+ /// ```toml
33+ /// [migrate]
34+ /// table_name = "foo._sqlx_migrations"
35+ /// ```
36+ pub table_name : Option < String > ,
37+
38+ /// Specify characters that should be ignored when hashing migrations.
39+ ///
40+ /// Any characters contained in the given string will be dropped when a migration is hashed.
41+ ///
42+ /// ### Example: Ignore Carriage Return (`<CR>` | `\r`)
43+ /// Line ending differences between platforms can result in migrations having non-repeatable
44+ /// hashes. The most common culprit is the carriage return (`<CR>` | `\r`), which Windows
45+ /// uses in its line endings alongside line feed (`<LF>` | `\n`), often written `CRLF` or `\r\n`,
46+ /// whereas Linux and macOS use only line feeds.
47+ ///
48+ /// `sqlx.toml`:
49+ /// ```toml
50+ /// [migrate]
51+ /// ignored_chars = "\r"
52+ /// ```
53+ ///
54+ /// For projects using Git, this can also be addressed using [`.gitattributes`]:
55+ ///
56+ /// ```text
57+ /// # Force newlines in migrations to be line feeds on all platforms
58+ /// migrations/*.sql text eol=lf
59+ /// ```
60+ ///
61+ /// This may require resetting or re-checking out the migrations files to take effect.
62+ ///
63+ /// [`.gitattributes`]: https://git-scm.com/docs/gitattributes
64+ ///
65+ /// ### Example: Ignore all Whitespace Characters
66+ /// To make your migrations amenable to reformatting, you may wish to tell SQLx to ignore
67+ /// _all_ whitespace characters in migrations.
68+ ///
69+ /// ##### Warning: Beware Syntatically Significant Whitespace!
70+ /// If your migrations use string literals or quoted identifiers which contain whitespace,
71+ /// this configuration will cause the migration machinery to ignore some changes to these.
72+ /// This may result in a mismatch between the development and production versions of
73+ /// your database.
74+ ///
75+ /// `sqlx.toml`:
76+ /// ```toml
77+ /// [migrate]
78+ /// # Ignore common whitespace characters when hashing
79+ /// ignored_chars = " \t\r\n"
80+ /// ```
81+ #[ serde( default ) ]
82+ pub ignored_chars : Box < str > ,
83+
84+ /// Specify the default type of migration that `sqlx migrate create` should create by default.
85+ ///
86+ /// ### Example: Use Reversible Migrations by Default
87+ /// `sqlx.toml`:
88+ /// ```toml
89+ /// [migrate]
90+ /// default_type = "reversible"
91+ /// ```
92+ pub default_type : DefaultMigrationType ,
93+
94+ /// Specify the default scheme that `sqlx migrate create` should use for version integers.
95+ ///
96+ /// ### Example: Use Sequential Versioning by Default
97+ /// `sqlx.toml`:
98+ /// ```toml
99+ /// [migrate]
100+ /// default_versioning = "sequential"
101+ /// ```
102+ pub default_versioning : DefaultVersioning ,
103+ }
104+
105+ /// The default type of migration that `sqlx migrate create` should create by default.
106+ #[ derive( Debug , Default , serde:: Deserialize ) ]
107+ #[ serde( rename_all = "snake_case" ) ]
108+ pub enum DefaultMigrationType {
109+ /// Create the same migration type as that of the latest existing migration,
110+ /// or `Simple` otherwise.
111+ #[ default]
112+ Inferred ,
113+
114+ /// Create a non-reversible migration (`<VERSION>_<DESCRIPTION>.sql`).
115+ Simple ,
116+
117+ /// Create a reversible migration (`<VERSION>_<DESCRIPTION>.up.sql` and `[...].down.sql`).
118+ Reversible
119+ }
120+
121+ /// The default scheme that `sqlx migrate create` should use for version integers.
122+ #[ derive( Debug , Default , serde:: Deserialize ) ]
123+ #[ serde( rename_all = "snake_case" ) ]
124+ pub enum DefaultVersioning {
125+ /// Infer the versioning scheme from existing migrations:
126+ ///
127+ /// * If the versions of the last two migrations differ by `1`, infer `Sequential`.
128+ /// * If only one migration exists and has version `1`, infer `Sequential`.
129+ /// * Otherwise, infer `Timestamp`.
130+ #[ default]
131+ Inferred ,
132+
133+ /// Use UTC timestamps for migration versions.
134+ ///
135+ /// This is the recommended versioning format as it's less likely to collide when multiple
136+ /// developers are creating migrations on different branches.
137+ ///
138+ /// The exact timestamp format is unspecified.
139+ Timestamp ,
140+
141+ /// Use sequential integers for migration versions.
142+ Sequential
143+ }
0 commit comments