From 46dd26045b433cf4a1eb7eeb1099c9bb21c7220d Mon Sep 17 00:00:00 2001 From: Austin Bonander Date: Sat, 27 Jul 2024 02:29:58 -0700 Subject: [PATCH] WIP feat: create `sqlx.toml` format --- Cargo.toml | 10 +- sqlx-core/Cargo.toml | 8 +- sqlx-core/src/config/macros.rs | 316 +++++++++++++++++++++++++++- sqlx-core/src/config/migrate.rs | 29 ++- sqlx-core/src/config/mod.rs | 74 +++++-- sqlx-core/src/config/reference.toml | 150 +++++++++++++ sqlx-core/src/config/tests.rs | 86 ++++++++ sqlx-core/src/lib.rs | 2 +- sqlx-macros-core/Cargo.toml | 4 + sqlx-macros/Cargo.toml | 3 + src/lib.rs | 7 +- 11 files changed, 649 insertions(+), 40 deletions(-) create mode 100644 sqlx-core/src/config/reference.toml create mode 100644 sqlx-core/src/config/tests.rs diff --git a/Cargo.toml b/Cargo.toml index 886451a73a..17c7772110 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -48,7 +48,7 @@ authors.workspace = true repository.workspace = true [package.metadata.docs.rs] -features = ["all-databases", "_unstable-all-types"] +features = ["all-databases", "_unstable-all-types", "_unstable-doc"] rustdoc-args = ["--cfg", "docsrs"] [features] @@ -58,9 +58,9 @@ derive = ["sqlx-macros/derive"] macros = ["derive", "sqlx-macros/macros"] migrate = ["sqlx-core/migrate", "sqlx-macros?/migrate", "sqlx-mysql?/migrate", "sqlx-postgres?/migrate", "sqlx-sqlite?/migrate"] -# Enable parsing of `sqlx.toml` for configuring macros, migrations, or both -config-macros = ["sqlx-core/config-macros"] -config-migrate = ["sqlx-core/config-migrate"] +# Enable parsing of `sqlx.toml` for configuring macros, migrations, or both. +config-macros = ["sqlx-macros?/config-macros"] +config-migrate = ["sqlx-macros?/config-migrate"] config-all = ["config-macros", "config-migrate"] # intended mainly for CI and docs @@ -76,6 +76,8 @@ _unstable-all-types = [ "uuid", "bit-vec", ] +# Render documentation that wouldn't otherwise be shown (e.g. `sqlx_core::config`). +_unstable-doc = ["config-all"] # Base runtime features without TLS runtime-async-std = ["_rt-async-std", "sqlx-core/_rt-async-std", "sqlx-macros?/_rt-async-std"] diff --git a/sqlx-core/Cargo.toml b/sqlx-core/Cargo.toml index 286f2aee7e..1ef5f6a3d3 100644 --- a/sqlx-core/Cargo.toml +++ b/sqlx-core/Cargo.toml @@ -12,7 +12,7 @@ features = ["offline"] [features] default = [] -migrate = ["sha2", "crc"] +migrate = ["sha2", "crc", "config-migrate"] any = [] @@ -28,9 +28,9 @@ _tls-none = [] # support offline/decoupled building (enables serialization of `Describe`) offline = ["serde", "either/serde"] -config-toml = ["serde", "toml/parse"] -config-macros = ["config-toml"] -config-migrate = ["config-toml"] +config = ["serde", "toml/parse"] +config-macros = ["config"] +config-migrate = ["config"] [dependencies] # Runtimes diff --git a/sqlx-core/src/config/macros.rs b/sqlx-core/src/config/macros.rs index dadbfcf0a4..399dc1c740 100644 --- a/sqlx-core/src/config/macros.rs +++ b/sqlx-core/src/config/macros.rs @@ -1,6 +1,316 @@ +use std::collections::BTreeMap; + /// Configuration for the [`sqlx::query!()`] family of macros. -#[derive(Debug, serde::Deserialize)] +#[derive(Debug, Default, serde::Deserialize)] +#[serde(default)] pub struct Config { - /// Override the environment variable + /// Override the database URL environment variable used by the macros. + /// + /// Case-sensitive. Defaults to `DATABASE_URL`. + /// + /// ### Example: Multi-Database Project + /// You can use multiple databases in the same project by breaking it up into multiple crates, + /// then using a different environment variable for each. + /// + /// For example, with two crates in the workspace named `foo` and `bar`: + /// + /// ##### `foo/sqlx.toml` + /// ```toml + /// [macros] + /// database_url_var = "FOO_DATABASE_URL" + /// ``` + /// + /// ##### `bar/sqlx.toml` + /// ```toml + /// [macros] + /// database_url_var = "BAR_DATABASE_URL" + /// ``` + /// + /// ##### `.env` + /// ```text + /// FOO_DATABASE_URL=postgres://postgres@localhost:5432/foo + /// BAR_DATABASE_URL=postgres://postgres@localhost:5432/bar + /// ``` + /// + /// The query macros used in `foo` will use `FOO_DATABASE_URL`, + /// and the ones used in `bar` will use `BAR_DATABASE_URL`. pub database_url_var: Option, -} \ No newline at end of file + + /// Specify the crate to use for mapping date/time types to Rust. + /// + /// The default behavior is to use whatever crate is enabled, + /// [`chrono`] or [`time`] (the latter takes precedent). + /// + /// [`chrono`]: crate::types::chrono + /// [`time`]: crate::types::time + /// + /// ### Example: Always Use Chrono + /// Thanks to Cargo's [feature unification], a crate in the dependency graph may enable + /// the `time` feature of SQLx which will force it on for all crates using SQLx, + /// which will result in problems if your crate wants to use types from [`chrono`]. + /// + /// You can use the type override syntax (see `sqlx::query!` for details), + /// or you can force an override globally by setting this option. + /// + /// ##### `sqlx.toml` + /// ```toml + /// [macros] + /// datetime_crate = "chrono" + /// ``` + /// + /// [feature unification]: https://doc.rust-lang.org/cargo/reference/features.html#feature-unification + pub datetime_crate: DateTimeCrate, + + /// Specify global overrides for mapping SQL type names to Rust type names. + /// + /// ### Note: Orthogonal to Nullability + /// These overrides do not affect whether `query!()` decides to wrap a column in `Option<_>` + /// or not. They only override the inner type used. + /// + /// ### Note: Schema Qualification (Postgres) + /// Type names may be schema-qualified in Postgres. If so, the schema should be part + /// of the type string, e.g. `'foo.bar'` to reference type `bar` in schema `foo`. + /// + /// The schema and/or type name may additionally be quoted in the string + /// for a quoted identifier (see next section). + /// + /// Postgres users: schema qualification should not be used for types in the search path. + /// + /// ### Note: Quoted Identifiers (Postgres) + /// Type names using [quoted identifiers] in SQL must also be specified with quotes here. + /// + /// Note, however, that the TOML format parses way the outer pair of quotes, + /// so for quoted names in SQL, double-quoting is necessary, + /// e.g. `'"Foo"'` for SQL type `"Foo"`. + /// + /// To reference a schema-qualified type with a quoted name, use double-quotes after the + /// dot, e.g. `'foo."Bar"'` to reference type `"Bar"` of schema `foo`, and vice versa for + /// quoted schema names. + /// + /// We recommend wrapping all type names in single quotes, as shown below, + /// to avoid confusion. + /// + /// [quoted identifiers]: https://www.postgresql.org/docs/current/sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS + // Note: we wanted to be able to handle this intelligently, + // but the `toml` crate authors weren't interested: https://github.com/toml-rs/toml/issues/761 + // + // We decided to just encourage always quoting type names instead. + /// ### Example: Custom Wrapper Types + /// Does SQLx not support a type that you need? Do you want additional semantics not + /// implemented on the built-in types? You can create a custom wrapper, + /// or use an external crate. + /// + /// ##### `sqlx.toml` + /// ```toml + /// [macros.type_overrides] + /// # Override a built-in type + /// 'uuid' = "crate::types::MyUuid" + /// + /// # Support an external or custom wrapper type (e.g. from the `isn` Postgres extension) + /// # (NOTE: FOR DOCUMENTATION PURPOSES ONLY; THIS CRATE/TYPE DOES NOT EXIST AS OF WRITING) + /// 'isbn13' = "isn_rs::sqlx::ISBN13" + /// + /// ### Example: Custom Types in Postgres + /// If you have a custom type in Postgres that you want to map without needing to use + /// the type override syntax in `sqlx::query!()` every time, you can specify a global + /// override here. + /// + /// For example, a custom enum type `foo`: + /// + /// ##### Migration or Setup SQL (e.g. `migrations/0_setup.sql`) + /// ```sql + /// CREATE TYPE foo AS ENUM ('Bar', 'Baz'); + /// ``` + /// + /// ##### `src/types.rs` + /// ```rust,no_run + /// #[derive(sqlx::Type)] + /// pub enum Foo { + /// Bar, + /// Baz + /// } + /// ``` + /// + /// If you're not using `PascalCase` in your enum variants then you'll want to use + /// `#[sqlx(rename_all = "")]` on your enum. + /// See [`Type`][crate::type::Type] for details. + /// + /// ##### `sqlx.toml` + /// ```toml + /// [macros.type_overrides] + /// # Map SQL type `foo` to `crate::types::Foo` + /// 'foo' = "crate::types::Foo" + /// ``` + /// + /// ### Example: Schema-Qualified Types + /// (See `Note` section above for details.) + /// + /// ```toml + /// [macros.type_overrides] + /// # Map SQL type `foo.foo` to `crate::types::Foo` + /// 'foo.foo' = "crate::types::Foo" + /// ``` + /// + /// ### Example: Quoted Identifiers + /// If a type or schema uses quoted identifiers, + /// it must be wrapped in quotes _twice_ for SQLx to know the difference: + /// + /// ```toml + /// [macros.type_overrides] + /// # `"Foo"` in SQLx + /// '"Foo"' = "crate::types::Foo" + /// # **NOT** `"Foo"` in SQLx (parses as just `Foo`) + /// "Foo" = "crate::types::Foo" + /// + /// # Schema-qualified + /// '"foo".foo' = "crate::types::Foo" + /// 'foo."Foo"' = "crate::types::Foo" + /// '"foo"."Foo"' = "crate::types::Foo" + /// ``` + /// + /// (See `Note` section above for details.) + pub type_overrides: BTreeMap, + + /// Specify overrides for mapping SQL types to Rust types, per table and column. + /// + /// The supported syntax is similar to [`type_overrides`][Self::type_overrides], + /// (with the same caveat for quoted names!) but column names must be qualified + /// by a separately quoted table name, which may optionally be schema-qualified. + /// + /// For example, column `bar` of table `foo` should be written `'foo'.'bar'`. + /// + /// Multiple columns for the same SQL table may be written in the same table in TOML + /// (see examples below). + /// + /// ### Note: Orthogonal to Nullability + /// These overrides do not affect whether `query!()` decides to wrap a column in `Option<_>` + /// or not. They only override the inner type used. + /// + /// ### Note: Schema Qualification (Postgres) + /// Table names may be schema-qualified in Postgres. If so, the schema should be part + /// of the table name string, e.g. `'foo.bar'` to reference table `bar` in schema `foo`. + /// + /// The schema and/or type name may additionally be quoted in the string + /// for a quoted identifier (see next section). + /// + /// Postgres users: schema qualification should not be used for types in the search path. + /// + /// ### Note: Quoted Identifiers (Postgres) + /// Schema, table, or column names using [quoted identifiers] in SQL + /// must also be specified with quotes here. + /// + /// Note, however, that the TOML format parses way the outer pair of quotes, + /// so for quoted names in SQL, double-quoting is necessary, + /// e.g. `'"Foo"'` for SQL name `"Foo"`. + /// + /// To reference a schema-qualified table with a quoted name, use double-quotes after the + /// dot, e.g. `'foo."Bar"'` to reference table `"Bar"` of schema `foo`, and vice versa for + /// quoted schema names. + /// + /// We recommend wrapping all table and column names in single quotes, as shown below, + /// to avoid confusion. + /// + /// [quoted identifiers]: https://www.postgresql.org/docs/current/sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS + // Note: we wanted to be able to handle this intelligently, + // but the `toml` crate authors weren't interested: https://github.com/toml-rs/toml/issues/761 + // + // We decided to just encourage always quoting type names instead. + /// + /// ### Example + /// + /// ##### `sqlx.toml` + /// ```toml + /// [macros.table_overrides] + /// # Map column `bar` of table `foo` to Rust type `crate::types::Foo`: + /// 'foo'.'bar' = "crate::types::Bar" + /// + /// # Quoted column name + /// # Note: same quoting requirements as `macros.type_overrides` + /// 'foo'.'"Bar"' = "crate::types::Bar" + /// + /// # Schema-qualified + /// # Note how the schema and table are together in a single string. + /// # Map column `baz` of table `foo.bar` to Rust type `crate::types::Baz` + /// 'foo.bar'.'baz' = "crate::types::Baz" + /// + /// # Schema, table and/or column names may be quoted + /// '"Foo"."Bar"'.'"Baz"' = "crate::types::Baz" + /// + /// # Multiple columns in the same table (`bar`) + /// [macros.table_overrides.'bar'] + /// # bar.foo + /// 'foo' = "crate::schema::bar::Foo" + /// # bar."Bar" + /// '"Bar"' = "crate::schema::bar::Bar" + /// + /// # May also be schema-qualified + /// # Note how the schema and table are together in a single string. + /// [macros.column_overrides.'my_schema.my_table'] + /// # my_schema.my_table.my_column + /// 'my_column' = "crate::types::MyType" + /// + /// # And quoted + /// [macros.column_overrides.'"My Schema"."My Table"'] + /// # "My Schema"."My Table"."My Column" + /// '"My Column"' = "crate::types::MyType" + /// ``` + pub table_overrides: BTreeMap>, +} + +/// The crate to use for mapping date/time types to Rust. +#[derive(Debug, Default, PartialEq, Eq, serde::Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum DateTimeCrate { + /// Use whichever crate is enabled (`time` then `chrono`). + #[default] + Inferred, + + /// Always use types from [`chrono`][crate::types::chrono]. + /// + /// ```toml + /// [macros] + /// datetime_crate = "chrono" + /// ``` + Chrono, + + /// Always use types from [`time`][crate::types::time]. + /// + /// ```toml + /// [macros] + /// datetime_crate = "time" + /// ``` + Time +} + +/// A SQL type name; may optionally be schema-qualified. +/// +/// See [`macros.type_overrides`][Config::type_overrides] for usages. +pub type SqlType = Box; + +/// A SQL table name; may optionally be schema-qualified. +/// +/// See [`macros.table_overrides`][Config::table_overrides] for usages. +pub type TableName = Box; + +/// A column in a SQL table. +/// +/// See [`macros.table_overrides`][Config::table_overrides] for usages. +pub type ColumnName = Box; + +/// A Rust type name or path. +/// +/// Should be a global path (not relative). +pub type RustType = Box; + +#[doc(hidden)] +impl Config { + pub fn type_override(&self, type_name: &str) -> Option<&str> { + self.type_overrides.get(type_name).map(|s| &**s) + } + + pub fn table_override(&self, table: &str, column: &str) -> Option<&str> { + self.table_overrides.get(table) + .and_then(|by_column| by_column.get(column)) + .map(|s| &**s) + } +} diff --git a/sqlx-core/src/config/migrate.rs b/sqlx-core/src/config/migrate.rs index 234eb24127..678c096d4e 100644 --- a/sqlx-core/src/config/migrate.rs +++ b/sqlx-core/src/config/migrate.rs @@ -2,15 +2,16 @@ /// /// ### Note /// A manually constructed [`Migrator`][crate::migrate::Migrator] will not be aware of these -/// configuration options. We recommend using [`sqlx::migrate!()`] instead. +/// configuration options. We recommend using `sqlx::migrate!()` instead. /// /// ### Warning: Potential Data Loss or Corruption! /// Many of these options, if changed after migrations are set up, /// can result in data loss or corruption of a production database /// if the proper precautions are not taken. /// -/// Be sure you know what you are doing and to read all relevant documentation _thoroughly_. -#[derive(Debug, serde::Deserialize)] +/// Be sure you know what you are doing and that you read all relevant documentation _thoroughly_. +#[derive(Debug, Default, serde::Deserialize)] +#[serde(default)] pub struct Config { /// Override the name of the table used to track executed migrations. /// @@ -33,12 +34,23 @@ pub struct Config { /// [migrate] /// table_name = "foo._sqlx_migrations" /// ``` - pub table_name: Option, + pub table_name: Option>, + + /// Override the directory used for migrations files. + /// + /// Relative to the crate root for `sqlx::migrate!()`, or the current directory for `sqlx-cli`. + pub migrations_dir: Option>, /// Specify characters that should be ignored when hashing migrations. /// /// Any characters contained in the given string will be dropped when a migration is hashed. /// + /// ### Warning: May Change Hashes for Existing Migrations + /// Changing the characters considered in hashing migrations will likely + /// change the output of the hash. + /// + /// This may require manual rectification for deployed databases. + /// /// ### Example: Ignore Carriage Return (`` | `\r`) /// Line ending differences between platforms can result in migrations having non-repeatable /// hashes. The most common culprit is the carriage return (`` | `\r`), which Windows @@ -76,9 +88,8 @@ pub struct Config { /// ```toml /// [migrate] /// # Ignore common whitespace characters when hashing - /// ignored_chars = " \t\r\n" + /// ignored_chars = " \t\r\n" # Space, tab, CR, LF /// ``` - #[serde(default)] pub ignored_chars: Box, /// Specify the default type of migration that `sqlx migrate create` should create by default. @@ -103,7 +114,7 @@ pub struct Config { } /// The default type of migration that `sqlx migrate create` should create by default. -#[derive(Debug, Default, serde::Deserialize)] +#[derive(Debug, Default, PartialEq, Eq, serde::Deserialize)] #[serde(rename_all = "snake_case")] pub enum DefaultMigrationType { /// Create the same migration type as that of the latest existing migration, @@ -119,7 +130,7 @@ pub enum DefaultMigrationType { } /// The default scheme that `sqlx migrate create` should use for version integers. -#[derive(Debug, Default, serde::Deserialize)] +#[derive(Debug, Default, PartialEq, Eq, serde::Deserialize)] #[serde(rename_all = "snake_case")] pub enum DefaultVersioning { /// Infer the versioning scheme from existing migrations: @@ -140,4 +151,4 @@ pub enum DefaultVersioning { /// Use sequential integers for migration versions. Sequential -} \ No newline at end of file +} diff --git a/sqlx-core/src/config/mod.rs b/sqlx-core/src/config/mod.rs index f75be068ea..af77d23992 100644 --- a/sqlx-core/src/config/mod.rs +++ b/sqlx-core/src/config/mod.rs @@ -1,32 +1,63 @@ -//! Support for reading and caching configuration data from `sqlx.toml` +//! (Exported for documentation only) Guide and reference for `sqlx.toml` files. +//! +//! To use, create a `sqlx.toml` file in your crate root (the same directory as your `Cargo.toml`). +//! The configuration in a `sqlx.toml` configures SQLx *only* for the current crate. +//! +//! See the [`Config`] type and its fields for individual configuration options. +//! +//! See the [reference][`_reference`] for the full `sqlx.toml` file. use std::fmt::Debug; +use std::io; use std::path::PathBuf; +// `std::sync::OnceLock` doesn't have a stable `.get_or_try_init()` +// because it's blocked on a stable `Try` trait. +use once_cell::sync::OnceCell; + +/// Configuration for the [`sqlx::query!()`] family of macros. +/// +/// See [`macros::Config`] for details. #[cfg(feature = "config-macros")] pub mod macros; +/// Configuration for migrations when executed using `sqlx::migrate!()` or through `sqlx-cli`. +/// +/// See [`migrate::Config`] for details. #[cfg(feature = "config-migrate")] pub mod migrate; +/// Reference for `sqlx.toml` files +/// +/// Source: `sqlx-core/src/config/reference.toml` +/// +/// ```toml +#[doc = include_str!("reference.toml")] +/// ``` +pub mod _reference {} + +#[cfg(test)] +mod tests; + /// The parsed structure of a `sqlx.toml` file. -#[derive(Debug, serde::Deserialize)] +#[derive(Debug, Default, serde::Deserialize)] pub struct Config { /// Configuration for the [`sqlx::query!()`] family of macros. - /// - /// See type documentation for details. + /// + /// See [`macros::Config`] for details. #[cfg_attr(docsrs, doc(cfg(any(feature = "config-all", feature = "config-macros"))))] #[cfg(feature = "config-macros")] pub macros: macros::Config, /// Configuration for migrations when executed using `sqlx::migrate!()` or through `sqlx-cli`. /// - /// See type documentation for details. + /// See [`migrate::Config`] for details. #[cfg_attr(docsrs, doc(cfg(any(feature = "config-all", feature = "config-migrate"))))] #[cfg(feature = "config-migrate")] pub migrate: migrate::Config, } +#[doc(hidden)] #[derive(thiserror::Error, Debug)] pub enum ConfigError { #[error("CARGO_MANIFEST_DIR must be set and valid")] @@ -35,7 +66,7 @@ pub enum ConfigError { #[error("error reading config file {path:?}")] Read { path: PathBuf, - #[source] error: std::io::Error, + #[source] error: io::Error, }, #[error("error parsing config file {path:?}")] @@ -45,11 +76,30 @@ pub enum ConfigError { } } +static CACHE: OnceCell = OnceCell::new(); + #[doc(hidden)] #[allow(clippy::result_large_err)] impl Config { + pub fn get() -> &'static Self { - Self::try_get().unwrap() + Self::try_get() + .unwrap_or_else(|e| { + match e { + ConfigError::Read { path, error } + if error.kind() == io::ErrorKind::NotFound => + { + // Non-fatal + tracing::debug!("Not reading config, file {path:?} not found"); + CACHE.get_or_init(|| Config::default()) + } + e => { + // In the case of migrations, + // we can't proceed with defaults as they may be completely wrong. + panic!("failed to read sqlx config: {e}") + } + } + }) } pub fn try_get() -> Result<&'static Self, ConfigError> { @@ -61,12 +111,6 @@ impl Config { } pub fn try_get_with(make_path: impl FnOnce() -> Result) -> Result<&'static Self, ConfigError> { - // `std::sync::OnceLock` doesn't have a stable `.get_or_try_init()` - // because it's blocked on a stable `Try` trait. - use once_cell::sync::OnceCell; - - static CACHE: OnceCell = OnceCell::new(); - CACHE.get_or_try_init(|| { let path = make_path()?; Self::read_from(path) @@ -84,7 +128,9 @@ impl Config { }); } }; - + + // TODO: parse and lint TOML structure before deserializing + // Motivation: https://github.com/toml-rs/toml/issues/761 tracing::debug!("read config TOML from {path:?}:\n{toml_s}"); toml::from_str(&toml_s).map_err(|error| { diff --git a/sqlx-core/src/config/reference.toml b/sqlx-core/src/config/reference.toml new file mode 100644 index 0000000000..8b8cb79241 --- /dev/null +++ b/sqlx-core/src/config/reference.toml @@ -0,0 +1,150 @@ +# Configuration for the `query!()` family of macros. +[macros] +# Change the environment variable to get the database URL for macro invocations in the current crate. +# If not specified, defaults to `DATABASE_URL` +database_url_var = "FOO_DATABASE_URL" + +# Force the macros to use the `chrono` crate for date/time types, even if `time` is enabled. +datetime_crate = "chrono" + +# Or, ensure the macros always prefer `time` (in case new time crates are added in the future) +# datetime_crate = "time" + +# Set global overrides for mapping SQL types to Rust types. +# +# ### Note: Orthogonal to Nullability +# These overrides do not affect whether `query!()` decides to wrap a column in `Option<_>` +# or not. They only override the inner type used. +[macros.type_overrides] +# Override a built-in type (map all `UUID` columns to `crate::types::MyUuid`) +'uuid' = "crate::types::MyUuid" + +# Support an external or custom wrapper type (e.g. from the `isn` Postgres extension) +# (NOTE: FOR DOCUMENTATION PURPOSES ONLY; THIS CRATE/TYPE DOES NOT EXIST AS OF WRITING) +'isbn13' = "isn_rs::isbn::ISBN13" + +# SQL type `foo` to Rust type `crate::types::Foo`: +'foo' = "crate::types::Foo" + +# SQL type `"Bar"` to Rust type `crate::types::Bar`; notice the extra pair of quotes: +'"Bar"' = "crate::types::Bar" + +# Will NOT work (the first pair of quotes are parsed by TOML) +# "Bar" = "crate::types::Bar" + +# Schema qualified +'foo.bar' = "crate::types::Bar" + +# Schema qualified and quoted +'foo."Bar"' = "crate::schema::foo::Bar" + +# Quoted schema name +'"Foo".bar' = "crate::schema::foo::Bar" + +# Quoted schema and type name +'"Foo"."Bar"' = "crate::schema::foo::Bar" + +# Set per-column overrides for mapping SQL types to Rust types. +# +# Note: table name is required. +# +# ### Note: Orthogonal to Nullability +# These overrides do not affect whether `query!()` decides to wrap a column in `Option<_>` +# or not. They only override the inner type used. +[macros.table_overrides] +# Map column `bar` of table `foo` to Rust type `crate::types::Foo`: +'foo'.'bar' = "crate::types::Bar" + +# Quoted column name +# Note: same quoting requirements as `macros.type_overrides` +'foo'.'"Bar"' = "crate::types::Bar" + +# Schema-qualified +# Map column `bar` of table `foobar.foo` to Rust type `crate::types::Baz`: +'foobar.foo'.'bar' = "crate::types::Bar" + +# schema, table and/or column names may be quoted +# Don't forget the wrapping single quotes! +'"Foo"."Bar"'.'"Baz"' = "crate::types::Baz" + +# Multiple columns in the same table (`bar`) +[macros.table_overrides.'bar'] +# bar.foo +'foo' = "crate::schema::bar::Foo" +# bar."Bar" +'"Bar"' = "crate::schema::bar::Bar" + +# May also be schema-qualified +[macros.table_overrides.'my_schema.my_table'] +'my_column' = "crate::types::MyType" + +# And quoted +[macros.table_overrides.'"My Schema"."My Table"'] +'"My Column"' = "crate::types::MyType" + +# Configuration for migrations when executed using `sqlx::migrate!()` or through `sqlx-cli`. +# +# ### Note +# A manually constructed [`Migrator`][crate::migrate::Migrator] will not be aware of these +# configuration options. We recommend using `sqlx::migrate!()` instead. +# +# ### Warning: Potential Data Loss or Corruption! +# Many of these options, if changed after migrations are set up, +# can result in data loss or corruption of a production database +# if the proper precautions are not taken. +# +# Be sure you know what you are doing and that you read all relevant documentation _thoroughly_. +[migrate] +# Override the name of the table used to track executed migrations. +# +# May be schema-qualified. Defaults to `_sqlx_migrations`. +# +# Potentially useful for multi-tenant databases. +# +# ### Warning: Potential Data Loss or Corruption! +# Changing this option for a production database will likely result in data loss or corruption +# as the migration machinery will no longer be aware of what migrations have been applied +# and will attempt to re-run them. +# +# You should create the new table as a copy of the existing migrations table (with contents!), +# and be sure all instances of your application have been migrated to the new +# table before deleting the old one. +table_name = "foo._sqlx_migrations" + +# Override the directory used for migrations files. +# +# Relative to the crate root for `sqlx::migrate!()`, or the current directory for `sqlx-cli`. +migrations_dir = "foo/migrations" + +# Specify characters that should be ignored when hashing migrations. +# +# Any characters contained in the given string will be dropped when a migration is hashed. +# +# ### Warning: May Change Hashes for Existing Migrations +# Changing the characters considered in hashing migrations will likely +# change the output of the hash. +# +# This may require manual rectification for deployed databases. + +# Ignore Carriage Returns (`` | `\r`) +ignored_chars = "\r" + +# Ignore common whitespace characters (beware syntatically significant whitespace!) +# ignored_chars = " \t\r\n" # Space, tab, CR, LF + +# Specify reversible migrations by default (for `sqlx migrate create`). +# +# Defaults to "inferred": uses the type of the last migration, or "simple" otherwise. +default_type = "reversible" + +# Specify simple (non-reversible) migrations by default. +# default_type = "simple + +# Specify sequential versioning by default (for `sqlx migrate create`). +# +# Defaults to "inferred": guesses the versioning scheme from the latest migrations, +# or "timestamp" otherwise. +default_versioning = "sequential" + +# Specify timestamp versioning by default. +# default_versioning = "timestamp" diff --git a/sqlx-core/src/config/tests.rs b/sqlx-core/src/config/tests.rs new file mode 100644 index 0000000000..3bdc5aa4bc --- /dev/null +++ b/sqlx-core/src/config/tests.rs @@ -0,0 +1,86 @@ +use crate::config::{self, Config}; + +#[test] +fn reference_parses_as_config() { + let config: Config = toml::from_str(include_str!("reference.toml")) + // The `Display` impl of `toml::Error` is *actually* more useful than `Debug` + .unwrap_or_else(|e| panic!("expected reference.toml to parse as Config: {e}")); + + #[cfg(feature = "config-macros")] + assert_macros_config(&config.macros); + + #[cfg(feature = "config-migrate")] + assert_migrate_config(&config.migrate); +} + +#[cfg(feature = "config-macros")] +fn assert_macros_config(config: &config::macros::Config) { + use config::macros::*; + + assert_eq!(config.database_url_var.as_deref(), Some("FOO_DATABASE_URL")); + + assert_eq!(config.datetime_crate, DateTimeCrate::Chrono); + + // Type overrides + // Don't need to cover everything, just some important canaries. + assert_eq!(config.type_override("foo"), Some("crate::types::Foo")); + + assert_eq!( + config.type_override(r#""Bar""#), + Some("crate::types::Bar"), + ); + + assert_eq!( + config.type_override(r#""Foo".bar"#), + Some("crate::schema::foo::Bar"), + ); + + assert_eq!( + config.type_override(r#""Foo"."Bar""#), + Some("crate::schema::foo::Bar"), + ); + + // Column overrides + assert_eq!( + config.table_override("foo", "bar"), + Some("crate::types::Bar"), + ); + + assert_eq!( + config.table_override("foobar.foo", "bar"), + Some("crate::types::Bar"), + ); + + assert_eq!( + config.table_override(r#""Foo"."Bar""#, r#""Baz""#), + Some("crate::types::Baz") + ); + + assert_eq!( + config.table_override("bar", r#""Bar""#), + Some("crate::schema::bar::Bar"), + ); + + assert_eq!( + config.table_override("my_schema.my_table", "my_column"), + Some("crate::types::MyType"), + ); + + assert_eq!( + config.table_override(r#""My Schema"."My Table""#, r#""My Column""#), + Some("crate::types::MyType"), + ); +} + +#[cfg(feature = "config-migrate")] +fn assert_migrate_config(config: &config::migrate::Config) { + use config::migrate::*; + + assert_eq!(config.table_name.as_deref(), Some("foo._sqlx_migrations")); + assert_eq!(config.migrations_dir.as_deref(), Some("foo/migrations")); + + assert_eq!(&*config.ignored_chars, "\r"); + + assert_eq!(config.default_type, DefaultMigrationType::Reversible); + assert_eq!(config.default_versioning, DefaultVersioning::Sequential); +} diff --git a/sqlx-core/src/lib.rs b/sqlx-core/src/lib.rs index 029a631007..7b4c270d59 100644 --- a/sqlx-core/src/lib.rs +++ b/sqlx-core/src/lib.rs @@ -93,7 +93,7 @@ pub mod any; #[cfg(feature = "migrate")] pub mod testing; -#[cfg(feature = "config-toml")] +#[cfg(feature = "config")] pub mod config; pub use error::{Error, Result}; diff --git a/sqlx-macros-core/Cargo.toml b/sqlx-macros-core/Cargo.toml index fec34b6528..5033851947 100644 --- a/sqlx-macros-core/Cargo.toml +++ b/sqlx-macros-core/Cargo.toml @@ -22,6 +22,10 @@ derive = [] macros = [] migrate = ["sqlx-core/migrate"] +config = ["sqlx-core/config"] +config-macros = ["config", "sqlx-core/config-macros"] +config-migrate = ["config", "sqlx-core/config-migrate"] + # database mysql = ["sqlx-mysql"] postgres = ["sqlx-postgres"] diff --git a/sqlx-macros/Cargo.toml b/sqlx-macros/Cargo.toml index cb4d1b91c3..dd0fa138c0 100644 --- a/sqlx-macros/Cargo.toml +++ b/sqlx-macros/Cargo.toml @@ -25,6 +25,9 @@ derive = ["sqlx-macros-core/derive"] macros = ["sqlx-macros-core/macros"] migrate = ["sqlx-macros-core/migrate"] +config-macros = ["sqlx-macros-core/config-macros"] +config-migrate = ["sqlx-macros-core/config-migrate"] + # database mysql = ["sqlx-macros-core/mysql"] postgres = ["sqlx-macros-core/postgres"] diff --git a/src/lib.rs b/src/lib.rs index 2a393387fa..e2fd0b1567 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -159,8 +159,5 @@ pub mod prelude { pub use super::Type; } -/// (Documentation only) Guide and reference for `sqlx.toml` files. -#[cfg(doc)] -pub mod config { - pub use sqlx_core::config::*; -} +#[cfg(feature = "_unstable-doc")] +pub use sqlx_core::config;