about summary refs log tree commit diff
path: root/src
diff options
context:
space:
mode:
authorAlexander_Kabui <alexanderkabui@proton.me>2026-10-14 08:36:18 +0300
committerAlexander_Kabui <alexanderkabui@proton.me>2026-10-14 08:36:18 +0300
commitdfa576b0f821dc8a0beba7acebeed81dc831b17a (patch)
tree5e086108c3afe303ed1707289f0c25635670e8e9 /src
parent630fec9b00e85436638b93ebf8902579ae436247 (diff)
parent22ff53e2d65e47df27d76aa7420a146074c00282 (diff)
downloadgenenetwork4-dfa576b0f821dc8a0beba7acebeed81dc831b17a.tar.gz
Merge remote-tracking branch 'origin/gn4-devdb-switch' into gn4-integration
Diffstat (limited to 'src')
-rw-r--r--src/bin/gn-indexer.rs14
-rw-r--r--src/config.rs58
-rw-r--r--src/db.rs126
-rw-r--r--src/error.rs26
-rw-r--r--src/lib.rs2
-rw-r--r--src/main.rs25
-rw-r--r--src/routes/accessions.rs11
-rw-r--r--src/routes/datasets.rs50
-rw-r--r--src/routes/groups.rs92
-rw-r--r--src/routes/mapping_methods.rs11
-rw-r--r--src/routes/publications.rs17
-rw-r--r--src/routes/species.rs33
-rw-r--r--src/routes/traits.rs35
13 files changed, 270 insertions, 230 deletions
diff --git a/src/bin/gn-indexer.rs b/src/bin/gn-indexer.rs
index 57a3f57..2149669 100644
--- a/src/bin/gn-indexer.rs
+++ b/src/bin/gn-indexer.rs
@@ -72,6 +72,20 @@ fn main() -> ExitCode {
         publish_filter,
     };
 
+    // Fail loudly BEFORE touching the index when the database is
+    // unreachable: the crawl needs it, and a run must never build an
+    // empty index. The message names SQL_URI/GN4_DB_MODE so the cause is
+    // unambiguous. (The crawl itself also fails, but this makes the
+    // reason explicit and keeps the index untouched by construction.)
+    if let Err(error) = genenetwork4::db::probe() {
+        eprintln!(
+            "gn-indexer: database unreachable (SQL_URI; GN4_DB_MODE={:?}); refusing to build an \
+             index: {error}",
+            config.db_mode
+        );
+        return ExitCode::from(1);
+    }
+
     let result = match mode.as_str() {
         "full" => run_full(&run_config),
         "incremental" => run_incremental(&run_config),
diff --git a/src/config.rs b/src/config.rs
index 5030576..5ae2913 100644
--- a/src/config.rs
+++ b/src/config.rs
@@ -17,6 +17,12 @@ pub struct Config {
     /// mysql://user:password@host/database. Same SQL_URI config key
     /// GeneNetwork3 uses, so the two services can share configuration.
     pub sql_uri: String,
+    /// Whether the database is required (`production`) or optional
+    /// (`dev`). Set via the GN4_DB_MODE key. `production` (the default)
+    /// refuses to start when the database is unreachable; `dev` starts
+    /// loudly without it, with DB-backed routes disabled. See
+    /// `DbMode` and src/main.rs.
+    pub db_mode: DbMode,
     /// Base URL of the GeneNetwork3 API, used by proxy endpoints.
     /// Must end with a slash, e.g. http://127.0.0.1:5003/api/.
     pub gn3_url: String,
@@ -89,6 +95,12 @@ impl Config {
             "SQL_URI".to_string(),
             "mysql://webqtlout:webqtlout@127.0.0.1/db_webqtl".to_string(),
         );
+        // Preserve today's behaviour: with no GN4_DB_MODE set, gn4 still
+        // starts when the database is unreachable (it just logs loudly
+        // and answers DB-backed routes as 503). Flipping this default to
+        // `production` (refuse to start) is a consumer-facing behaviour
+        // change and needs owner sign-off -- see REPORT.md.
+        values.insert("GN4_DB_MODE".to_string(), "dev".to_string());
         values.insert("GENENETWORK4_PORT".to_string(), "3000".to_string());
         values.insert(
             "AUTH_SERVER_URL".to_string(),
@@ -151,6 +163,7 @@ impl Config {
         // Layer 4: environment wins over everything.
         for key in [
             "SQL_URI",
+            "GN4_DB_MODE",
             "GENENETWORK4_PORT",
             "AUTH_SERVER_URL",
             "GENENETWORK4_BIND",
@@ -177,6 +190,7 @@ impl Config {
 
         Config {
             sql_uri: values["SQL_URI"].clone(),
+            db_mode: parse_db_mode(&values["GN4_DB_MODE"]),
             gn3_url,
             gn3_timeout_secs: values["GN3_TIMEOUT_SECS"]
                 .parse()
@@ -201,6 +215,31 @@ impl Config {
     }
 }
 
+/// Reads the GN4_DB_MODE setting, failing closed: only the exact
+/// values `dev` and `production` (any case, trimmed) are accepted;
+/// anything else -- including a typo like "prodution" -- refuses to
+/// start rather than silently picking a mode. The empty string (an
+/// explicitly blank key) is likewise refused.
+fn parse_db_mode(value: &str) -> DbMode {
+    match value.trim().to_ascii_lowercase().as_str() {
+        "dev" => DbMode::Dev,
+        "production" => DbMode::Production,
+        other => panic!("GN4_DB_MODE must be \"dev\" or \"production\", not {other:?}"),
+    }
+}
+
+/// Whether the database is required for the process to serve.
+#[derive(Clone, Copy, PartialEq, Eq, Debug)]
+pub enum DbMode {
+    /// The database is optional: gn4 starts without a reachable
+    /// database, logging loudly and serving DB-backed routes as 503.
+    Dev,
+    /// The database is required: an unreachable/unconfigured database
+    /// at startup is a misconfiguration and the process refuses to
+    /// start (exit non-zero).
+    Production,
+}
+
 /// Reads an on/off setting, failing closed: only a clearly affirmative
 /// value ("true", "1", "yes", "on", any case) is on; "false", "0", "no",
 /// "off", the empty string and anything unrecognised (a typo like
@@ -253,6 +292,7 @@ mod tests {
     fn defaults_apply_with_no_files_or_env() {
         for key in [
             "SQL_URI",
+            "GN4_DB_MODE",
             "GN4_CONF",
             "GN4_SECRETS",
             "GENENETWORK4_PORT",
@@ -279,6 +319,11 @@ mod tests {
         }
         let config = Config::load();
         assert!(config.sql_uri.contains("db_webqtl"));
+        assert_eq!(
+            config.db_mode,
+            DbMode::Dev,
+            "no-DB start preserved; the production flip needs sign-off"
+        );
         assert_eq!(config.port, 3000);
         assert_eq!(config.gemma_wrapper_cmd, "gemma-wrapper");
         assert!(config.gemma_cache_dir.ends_with("gn4-gemma"));
@@ -295,6 +340,19 @@ mod tests {
     }
 
     #[test]
+    fn db_mode_accepts_only_dev_and_production() {
+        assert_eq!(parse_db_mode("dev"), DbMode::Dev);
+        assert_eq!(parse_db_mode(" DEV "), DbMode::Dev);
+        assert_eq!(parse_db_mode("production"), DbMode::Production);
+        assert_eq!(parse_db_mode("Production"), DbMode::Production);
+        // Fail-closed: a typo or a blank value must refuse, not default.
+        for bad in ["prodution", "prod", "", "none", "devmode"] {
+            let refused = std::panic::catch_unwind(|| parse_db_mode(bad)).is_err();
+            assert!(refused, "{bad:?} must be refused");
+        }
+    }
+
+    #[test]
     fn a_switch_is_on_only_for_a_clearly_affirmative_value() {
         for on in ["true", "TRUE", "True", "1", "yes", "ON", " on "] {
             assert!(parse_switch(on), "{on:?}");
diff --git a/src/db.rs b/src/db.rs
index ba22811..2675875 100644
--- a/src/db.rs
+++ b/src/db.rs
@@ -12,6 +12,42 @@ fn sql_uri() -> String {
     crate::config::Config::load().sql_uri
 }
 
+/// Why a database-backed operation failed.
+///
+/// The distinction is minted at the `pool()` choke point, the single
+/// place a connection is (re)established: `Unavailable` means the pool
+/// could not be built at all, so no configured/reachable database
+/// exists and DB-backed routes are meaningless (they map to a typed
+/// 503 `db_unavailable`). `Query` is any failure on an already-built
+/// pool -- a bad query, or a connection that died after the pool was
+/// built; those keep the existing 500 `database_error` shape. See the
+/// lane REPORT's probe-window limitation.
+#[derive(Debug)]
+pub enum DbError {
+    /// The pool could not be built: `SQL_URI` is unset/unparseable or
+    /// the database is unreachable. Minted only here.
+    Unavailable(String),
+    /// A query (or pool checkout) failed on an established pool.
+    Query(mysql::Error),
+}
+
+impl std::fmt::Display for DbError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            DbError::Unavailable(detail) => write!(f, "{detail}"),
+            DbError::Query(error) => write!(f, "{error}"),
+        }
+    }
+}
+
+impl std::error::Error for DbError {}
+
+impl From<mysql::Error> for DbError {
+    fn from(error: mysql::Error) -> Self {
+        DbError::Query(error)
+    }
+}
+
 /// The shared connection pool, built once and reused by every query
 /// function below. mysql::Pool::new eagerly opens PoolConstraints::
 /// DEFAULT's 10 connections before returning (about 7s against this
@@ -37,22 +73,39 @@ fn sql_uri() -> String {
 /// and the ping only protects against a connection the server closed
 /// while idle -- which would now surface as a database error on the
 /// next query using it (the pool then drops that connection).
-fn pool() -> Result<Pool, mysql::Error> {
+fn pool() -> Result<Pool, DbError> {
     static POOL: OnceLock<Mutex<Option<Pool>>> = OnceLock::new();
     let mut guard = POOL.get_or_init(|| Mutex::new(None)).lock().unwrap();
     if let Some(pool) = guard.as_ref() {
         return Ok(pool.clone());
     }
-    let opts = OptsBuilder::from_opts(Opts::from_url(&sql_uri())?).pool_opts(
+    let opts = OptsBuilder::from_opts(
+        Opts::from_url(&sql_uri()).map_err(|e| DbError::Unavailable(e.to_string()))?,
+    )
+    .pool_opts(
         PoolOpts::default()
             .with_reset_connection(false)
             .with_check_health(false),
     );
-    let new_pool = Pool::new(opts)?;
+    let new_pool = Pool::new(opts).map_err(|e| DbError::Unavailable(e.to_string()))?;
     *guard = Some(new_pool.clone());
     Ok(new_pool)
 }
 
+/// Startup reachability probe: builds the shared pool (connecting to
+/// `SQL_URI`) and runs `SELECT 1`. `Ok(())` means the database is
+/// reachable; an `Err` is exactly what makes DB-backed routes answer
+/// 503. Used by src/main.rs to refuse (`production`) or warn loudly
+/// (`dev`) before serving, and by gn-indexer to refuse before touching
+/// an index. The built pool is cached, so a successful probe warms the
+/// pool the routes then reuse.
+pub fn probe() -> Result<(), DbError> {
+    let pool = pool()?;
+    let mut conn = pool.get_conn()?;
+    conn.query_drop("SELECT 1")?;
+    Ok(())
+}
+
 /// GeneNetwork stores LRS (likelihood ratio statistic); LOD = LRS / 4.604
 /// (the divisor GeneNetwork's RDF data uses; 2 ln 10 is 4.605). Every
 /// `lod` the API reports is derived with this one constant -- in SQL for rows read from the database, via `lod` for
@@ -75,7 +128,7 @@ pub struct Species {
 }
 
 /// Mirrors GeneNetwork3's gn3.db.species.get_all_species.
-pub fn get_all_species() -> Result<Vec<Species>, mysql::Error> {
+pub fn get_all_species() -> Result<Vec<Species>, DbError> {
     let pool = pool()?;
     let mut conn = pool.get_conn()?;
     conn.query_map(
@@ -88,6 +141,7 @@ pub fn get_all_species() -> Result<Vec<Species>, mysql::Error> {
             family,
         },
     )
+    .map_err(DbError::from)
 }
 
 /// One full row of the Species table.
@@ -122,7 +176,7 @@ type SpeciesRow = (
 /// Fetch one species by Name, FullName or SpeciesName, matching
 /// GeneNetwork2's wqflask.api.router.get_species_info, but returning
 /// every column of the Species table rather than a fixed subset.
-pub fn get_species_by_name(name: &str) -> Result<Option<SpeciesDetail>, mysql::Error> {
+pub fn get_species_by_name(name: &str) -> Result<Option<SpeciesDetail>, DbError> {
     let pool = pool()?;
     let mut conn = pool.get_conn()?;
     conn.exec_first(
@@ -161,6 +215,7 @@ pub fn get_species_by_name(name: &str) -> Result<Option<SpeciesDetail>, mysql::E
             },
         )
     })
+    .map_err(DbError::from)
 }
 
 /// Summary of one InbredSet row, matching the shape of GeneNetwork2's
@@ -189,7 +244,7 @@ pub struct Group {
 
 /// Mirrors GeneNetwork2's wqflask.api.router.get_groups_list, plus the
 /// family and species name (filtering is done by the handler).
-pub fn get_all_groups() -> Result<Vec<Group>, mysql::Error> {
+pub fn get_all_groups() -> Result<Vec<Group>, DbError> {
     let pool = pool()?;
     let mut conn = pool.get_conn()?;
     conn.query_map(
@@ -229,6 +284,7 @@ pub fn get_all_groups() -> Result<Vec<Group>, mysql::Error> {
             }
         },
     )
+    .map_err(DbError::from)
 }
 
 /// One mapping tool GeneNetwork offers (a MappingMethod row), e.g.
@@ -241,13 +297,14 @@ pub struct MappingMethod {
     pub name: String,
 }
 
-pub fn get_mapping_methods() -> Result<Vec<MappingMethod>, mysql::Error> {
+pub fn get_mapping_methods() -> Result<Vec<MappingMethod>, DbError> {
     let pool = pool()?;
     let mut conn = pool.get_conn()?;
     conn.query_map(
         "SELECT Id, Name FROM MappingMethod ORDER BY Id",
         |(id, name)| MappingMethod { id, name },
     )
+    .map_err(DbError::from)
 }
 
 /// A GeneNetwork accession number (the "GN602" of a dataset's page): an
@@ -270,7 +327,7 @@ pub struct Accession {
 /// Resolve an accession number: its InfoFiles row, then the dataset of
 /// that name (PublishFreeze, else ProbeSetFreeze) for its category and
 /// group. None when no InfoFiles row has the accession.
-pub fn get_accession(accession: u32) -> Result<Option<Accession>, mysql::Error> {
+pub fn get_accession(accession: u32) -> Result<Option<Accession>, DbError> {
     let pool = pool()?;
     let mut conn = pool.get_conn()?;
     let row: Option<(String, Option<String>)> = conn.exec_first(
@@ -351,7 +408,7 @@ pub struct GroupDetail {
 /// doesn't match by Id) plus gn-guile's gn.data.population:population-info
 /// (which only matches by Id), returning every column of the InbredSet
 /// table rather than a fixed subset.
-pub fn get_group_by_name(name: &str) -> Result<Option<GroupDetail>, mysql::Error> {
+pub fn get_group_by_name(name: &str) -> Result<Option<GroupDetail>, DbError> {
     let pool = pool()?;
     let mut conn = pool.get_conn()?;
     conn.exec_first(
@@ -366,6 +423,7 @@ pub fn get_group_by_name(name: &str) -> Result<Option<GroupDetail>, mysql::Error
                 OR InbredSet.FullName = :name OR CAST(InbredSet.Id AS CHAR) = :name",
         mysql::params! { "name" => name },
     )
+    .map_err(DbError::from)
 }
 
 /// One strain/sample belonging to a group, matching gn-guile's
@@ -385,7 +443,7 @@ pub struct Strain {
 pub fn get_group_strains(
     group_id: u16,
     used_for_mapping: Option<bool>,
-) -> Result<Vec<Strain>, mysql::Error> {
+) -> Result<Vec<Strain>, DbError> {
     let pool = pool()?;
     let mut conn = pool.get_conn()?;
     conn.exec_map(
@@ -402,6 +460,7 @@ pub fn get_group_strains(
             used_for_mapping: used_for_mapping == "Y",
         },
     )
+    .map_err(DbError::from)
 }
 
 /// One strain's value for a published (phenotype) trait, matching
@@ -424,7 +483,7 @@ pub struct TraitValue {
 pub fn get_group_trait_values(
     group_id: u16,
     trait_id: u32,
-) -> Result<Vec<TraitValue>, mysql::Error> {
+) -> Result<Vec<TraitValue>, DbError> {
     let pool = pool()?;
     let mut conn = pool.get_conn()?;
     conn.exec_map(
@@ -436,6 +495,7 @@ pub fn get_group_trait_values(
         mysql::params! { "group_id" => group_id, "trait_id" => trait_id },
         |(name, value)| TraitValue { name, value },
     )
+    .map_err(DbError::from)
 }
 
 /// One published (phenotype) trait's metadata: its PublishXRef mapping
@@ -534,7 +594,7 @@ fn trait_info_sql(filter: &str, order_by: &str) -> String {
 pub fn get_group_trait_info(
     group_id: u16,
     trait_id: u32,
-) -> Result<Option<TraitInfo>, mysql::Error> {
+) -> Result<Option<TraitInfo>, DbError> {
     let pool = pool()?;
     let mut conn = pool.get_conn()?;
     conn.exec_first(
@@ -544,17 +604,19 @@ pub fn get_group_trait_info(
         ),
         mysql::params! { "group_id" => group_id, "trait_id" => trait_id },
     )
+    .map_err(DbError::from)
 }
 
 /// Fetch every published trait's metadata (see TraitInfo) within a
 /// group, the listing equivalent of get_group_trait_info.
-pub fn get_group_traits(group_id: u16) -> Result<Vec<TraitInfo>, mysql::Error> {
+pub fn get_group_traits(group_id: u16) -> Result<Vec<TraitInfo>, DbError> {
     let pool = pool()?;
     let mut conn = pool.get_conn()?;
     conn.exec(
         trait_info_sql("PublishXRef.InbredSetId = :group_id", "PublishXRef.Id"),
         mysql::params! { "group_id" => group_id },
     )
+    .map_err(DbError::from)
 }
 
 /// The traits of a group whose short name (either the post- or the
@@ -562,7 +624,7 @@ pub fn get_group_traits(group_id: u16) -> Result<Vec<TraitInfo>, mysql::Error> {
 pub fn get_group_traits_by_abbreviation(
     group_id: u16,
     abbreviation: &str,
-) -> Result<Vec<TraitInfo>, mysql::Error> {
+) -> Result<Vec<TraitInfo>, DbError> {
     let pool = pool()?;
     let mut conn = pool.get_conn()?;
     conn.exec(
@@ -574,11 +636,12 @@ pub fn get_group_traits_by_abbreviation(
         ),
         mysql::params! { "group_id" => group_id, "abbreviation" => abbreviation },
     )
+    .map_err(DbError::from)
 }
 
 /// Every published trait (across groups) reported in the publication
 /// with this PubMed id, or None when no such publication exists.
-pub fn get_publication_traits(pubmed_id: u32) -> Result<Option<Vec<TraitInfo>>, mysql::Error> {
+pub fn get_publication_traits(pubmed_id: u32) -> Result<Option<Vec<TraitInfo>>, DbError> {
     let pool = pool()?;
     let mut conn = pool.get_conn()?;
     let exists: Option<u32> = conn.exec_first(
@@ -596,6 +659,7 @@ pub fn get_publication_traits(pubmed_id: u32) -> Result<Option<Vec<TraitInfo>>,
         mysql::params! { "pubmed_id" => pubmed_id },
     )
     .map(Some)
+    .map_err(DbError::from)
 }
 
 /// What search hits are annotated with from PublishXRef/Phenotype
@@ -611,7 +675,7 @@ pub struct PublishAnnotation {
 /// exist are absent from the result.
 pub fn get_publish_annotations(
     keys: &[(String, u32)],
-) -> Result<std::collections::HashMap<(String, u32), PublishAnnotation>, mysql::Error> {
+) -> Result<std::collections::HashMap<(String, u32), PublishAnnotation>, DbError> {
     let pool = pool()?;
     let mut conn = pool.get_conn()?;
     let pairs = vec!["(?, ?)"; keys.len()].join(", ");
@@ -669,7 +733,7 @@ pub struct Dataset {
 /// GeneNetwork2's wqflask.api.router.get_datasets_for_group (without
 /// its species-scoped variant, which this API doesn't need: a group
 /// name alone already picks one species).
-pub fn get_group_datasets(group_id: u16) -> Result<Vec<Dataset>, mysql::Error> {
+pub fn get_group_datasets(group_id: u16) -> Result<Vec<Dataset>, DbError> {
     let pool = pool()?;
     let mut conn = pool.get_conn()?;
     conn.exec_map(
@@ -711,6 +775,7 @@ pub fn get_group_datasets(group_id: u16) -> Result<Vec<Dataset>, mysql::Error> {
             }
         },
     )
+    .map_err(DbError::from)
 }
 
 /// One strain's case-attribute values within a group: extra per-strain
@@ -743,13 +808,14 @@ pub struct CaseAttributes {
 /// (trimmed to just the name -- Description isn't used by genenetwork4
 /// yet, and CaseAttributeId/InbredSetId are already implied by this
 /// being scoped to one group).
-fn get_group_case_attribute_names(group_id: u16) -> Result<Vec<String>, mysql::Error> {
+fn get_group_case_attribute_names(group_id: u16) -> Result<Vec<String>, DbError> {
     let pool = pool()?;
     let mut conn = pool.get_conn()?;
     conn.exec(
         "SELECT Name FROM CaseAttribute WHERE InbredSetId = :group_id ORDER BY Name",
         mysql::params! { "group_id" => group_id },
     )
+    .map_err(DbError::from)
 }
 
 /// Fetch every strain's case-attribute values for a group, based on
@@ -769,7 +835,7 @@ fn get_group_case_attribute_names(group_id: u16) -> Result<Vec<String>, mysql::E
 /// ordered by strain name, so adjacent rows for the same strain are
 /// folded into one `StrainCaseAttributes` as they're read rather than
 /// grouped afterwards.
-fn get_group_case_attribute_values(group_id: u16) -> Result<Vec<StrainCaseAttributes>, mysql::Error> {
+fn get_group_case_attribute_values(group_id: u16) -> Result<Vec<StrainCaseAttributes>, DbError> {
     let pool = pool()?;
     let mut conn = pool.get_conn()?;
     let rows: Vec<(String, String, String)> = conn.exec(
@@ -804,7 +870,7 @@ fn get_group_case_attribute_values(group_id: u16) -> Result<Vec<StrainCaseAttrib
 
 /// Fetch a group's case attributes: every attribute name defined for
 /// it, and every strain's values for them. See `CaseAttributes`.
-pub fn get_group_case_attributes(group_id: u16) -> Result<CaseAttributes, mysql::Error> {
+pub fn get_group_case_attributes(group_id: u16) -> Result<CaseAttributes, DbError> {
     Ok(CaseAttributes {
         names: get_group_case_attribute_names(group_id)?,
         values: get_group_case_attribute_values(group_id)?,
@@ -816,7 +882,7 @@ pub fn get_group_case_attributes(group_id: u16) -> Result<CaseAttributes, mysql:
 /// GeneNetwork2's own species-scoped variant of
 /// wqflask.api.router.get_datasets_for_group still requires a group
 /// name (species only disambiguates it); this doesn't need one.
-pub fn get_species_datasets(species_id: u16) -> Result<Vec<Dataset>, mysql::Error> {
+pub fn get_species_datasets(species_id: u16) -> Result<Vec<Dataset>, DbError> {
     let pool = pool()?;
     let mut conn = pool.get_conn()?;
     conn.exec_map(
@@ -859,6 +925,7 @@ pub fn get_species_datasets(species_id: u16) -> Result<Vec<Dataset>, mysql::Erro
             }
         },
     )
+    .map_err(DbError::from)
 }
 
 /// Columns of the Dataset row, in SELECT order.
@@ -879,7 +946,7 @@ type DatasetRow = (
 /// Fetch one dataset by Name, Name2, FullName, ShortName or numeric
 /// Id, matching GeneNetwork2's wqflask.api.router.get_dataset_info's
 /// matching logic for its ProbeSet (mRNA expression) branch.
-pub fn get_dataset_by_name(name: &str) -> Result<Option<Dataset>, mysql::Error> {
+pub fn get_dataset_by_name(name: &str) -> Result<Option<Dataset>, DbError> {
     let pool = pool()?;
     let mut conn = pool.get_conn()?;
     conn.exec_first(
@@ -926,6 +993,7 @@ pub fn get_dataset_by_name(name: &str) -> Result<Option<Dataset>, mysql::Error>
             },
         )
     })
+    .map_err(DbError::from)
 }
 
 /// One row of the PublishFreeze table -- the Publish/phenotype
@@ -954,7 +1022,7 @@ pub struct PublishDataset {
 /// owning group's Id/Name/InbredSetName/FullName -- mirroring
 /// GeneNetwork2's wqflask.api.router.trait_sample_data's Publish
 /// branch, which accepts either (e.g. "BXDPublish" or plain "BXD").
-pub fn get_publish_freeze_by_name(name: &str) -> Result<Option<PublishDataset>, mysql::Error> {
+pub fn get_publish_freeze_by_name(name: &str) -> Result<Option<PublishDataset>, DbError> {
     let pool = pool()?;
     let mut conn = pool.get_conn()?;
     conn.exec_first(
@@ -970,6 +1038,7 @@ pub fn get_publish_freeze_by_name(name: &str) -> Result<Option<PublishDataset>,
                 OR InbredSet.FullName = :name OR CAST(InbredSet.Id AS CHAR) = :name",
         mysql::params! { "name" => name },
     )
+    .map_err(DbError::from)
 }
 
 /// Which category a `/traits/{dataset}/...` request's dataset resolved
@@ -984,7 +1053,7 @@ pub enum TraitDataset {
 /// then PublishFreeze (a dataset name is expected to match at most one
 /// of these). Geno/GenoFreeze isn't supported yet, matching the rest
 /// of this API.
-pub fn resolve_trait_dataset(name: &str) -> Result<Option<TraitDataset>, mysql::Error> {
+pub fn resolve_trait_dataset(name: &str) -> Result<Option<TraitDataset>, DbError> {
     if let Some(dataset) = get_dataset_by_name(name)? {
         return Ok(Some(TraitDataset::ProbeSet(dataset)));
     }
@@ -1041,7 +1110,7 @@ type ProbeSetInfoRow = (
 pub fn get_dataset_probeset_info(
     dataset_id: u16,
     probeset_name: &str,
-) -> Result<Option<ProbeSetInfo>, mysql::Error> {
+) -> Result<Option<ProbeSetInfo>, DbError> {
     let pool = pool()?;
     let mut conn = pool.get_conn()?;
     conn.exec_first(
@@ -1089,12 +1158,13 @@ pub fn get_dataset_probeset_info(
             },
         )
     })
+    .map_err(DbError::from)
 }
 
 /// Fetch every expression (ProbeSet) trait's metadata (see
 /// ProbeSetInfo) within a dataset, the listing equivalent of
 /// get_dataset_probeset_info.
-pub fn get_dataset_probesets(dataset_id: u16) -> Result<Vec<ProbeSetInfo>, mysql::Error> {
+pub fn get_dataset_probesets(dataset_id: u16) -> Result<Vec<ProbeSetInfo>, DbError> {
     let pool = pool()?;
     let mut conn = pool.get_conn()?;
     conn.exec_map(
@@ -1139,6 +1209,7 @@ pub fn get_dataset_probesets(dataset_id: u16) -> Result<Vec<ProbeSetInfo>, mysql
             }
         },
     )
+    .map_err(DbError::from)
 }
 
 /// One strain's value for an expression (ProbeSet) trait, matching
@@ -1156,7 +1227,7 @@ pub struct ProbeSetValue {
 pub fn get_dataset_probeset_values(
     dataset_id: u16,
     probeset_name: &str,
-) -> Result<Vec<ProbeSetValue>, mysql::Error> {
+) -> Result<Vec<ProbeSetValue>, DbError> {
     let pool = pool()?;
     let mut conn = pool.get_conn()?;
     conn.exec_map(
@@ -1169,4 +1240,5 @@ pub fn get_dataset_probeset_values(
         mysql::params! { "dataset_id" => dataset_id, "probeset_name" => probeset_name },
         |(name, value)| ProbeSetValue { name, value },
     )
+    .map_err(DbError::from)
 }
diff --git a/src/error.rs b/src/error.rs
index 3f9479a..7daa103 100644
--- a/src/error.rs
+++ b/src/error.rs
@@ -111,6 +111,32 @@ impl ApiError {
         self.next = Some(next.to_string());
         self
     }
+
+    /// Map a database failure onto the shared error contract. An
+    /// unreachable/unconfigured database (minted at `db::pool()`) is a
+    /// typed 503 `db_unavailable` -- the database itself is down, not
+    /// this request; a query failure on an established pool keeps the
+    /// existing 500 `database_error`. Every DB-touching route maps
+    /// through this one place, so all four `From`-adapter shapes and
+    /// the inline `map_err` sites agree.
+    pub fn from_db(error: crate::db::DbError, operation_id: &str) -> ApiError {
+        match error {
+            crate::db::DbError::Unavailable(detail) => ApiError::new(
+                StatusCode::SERVICE_UNAVAILABLE,
+                "db_unavailable",
+                "Database unavailable",
+                detail,
+                operation_id,
+            ),
+            crate::db::DbError::Query(error) => ApiError::new(
+                StatusCode::INTERNAL_SERVER_ERROR,
+                "database_error",
+                "Database error",
+                error.to_string(),
+                operation_id,
+            ),
+        }
+    }
 }
 
 impl IntoResponse for ApiError {
diff --git a/src/lib.rs b/src/lib.rs
index f011219..9297d87 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -8,7 +8,7 @@ use utoipa_axum::routes;
 
 pub mod auth;
 pub mod config;
-mod db;
+pub mod db;
 pub mod embedded;
 mod error;
 pub mod indexer;
diff --git a/src/main.rs b/src/main.rs
index 21a0e55..39c9c1d 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -1,6 +1,31 @@
+use genenetwork4::config::DbMode;
+
 #[tokio::main]
 async fn main() {
     let config = genenetwork4::config::Config::load();
+    // Startup database probe (`SELECT 1` through the shared pool),
+    // BEFORE the listener is bound. `production` treats an unreachable
+    // database as a misconfiguration and refuses to start; `dev` starts
+    // anyway, loudly, with DB-backed routes answering the typed 503
+    // (src/error.rs). The message names both config keys so the refusal
+    // is unambiguous.
+    if let Err(error) = genenetwork4::db::probe() {
+        match config.db_mode {
+            DbMode::Production => {
+                eprintln!(
+                    "FATAL: GN4_DB_MODE=production requires a reachable database, but SQL_URI \
+                     is unreachable or unconfigured ({error}); refusing to start."
+                );
+                std::process::exit(1);
+            }
+            DbMode::Dev => {
+                eprintln!(
+                    "database not configured/unreachable — DB-backed routes disabled \
+                     (GN4_DB_MODE=dev, SQL_URI unreachable or unconfigured): {error}"
+                );
+            }
+        }
+    }
     let bind_ip: std::net::IpAddr = config
         .bind
         .parse()
diff --git a/src/routes/accessions.rs b/src/routes/accessions.rs
index c55bfd7..66801e0 100644
--- a/src/routes/accessions.rs
+++ b/src/routes/accessions.rs
@@ -58,16 +58,7 @@ pub async fn accession(
             )
             .with_request_id(rid.clone())
         })?
-        .map_err(|e| {
-            ApiError::new(
-                StatusCode::INTERNAL_SERVER_ERROR,
-                "database_error",
-                "Database error",
-                e.to_string(),
-                "accession",
-            )
-            .with_request_id(rid.clone())
-        })?
+        .map_err(|e| ApiError::from_db(e, "accession").with_request_id(rid.clone()))?
         .map(|found| {
             let group = found.group.as_deref().map(path_segment);
             let name = path_segment(&found.name);
diff --git a/src/routes/datasets.rs b/src/routes/datasets.rs
index b011099..8c903ce 100644
--- a/src/routes/datasets.rs
+++ b/src/routes/datasets.rs
@@ -41,16 +41,7 @@ pub async fn dataset_by_name(
             )
             .with_request_id(rid.clone())
         })?
-        .map_err(|e| {
-            ApiError::new(
-                StatusCode::INTERNAL_SERVER_ERROR,
-                "database_error",
-                "Database error",
-                e.to_string(),
-                "dataset_by_name",
-            )
-            .with_request_id(rid.clone())
-        })?
+        .map_err(|e| ApiError::from_db(e, "dataset_by_name").with_request_id(rid.clone()))?
         .map(|dataset| {
             Json(ctx.envelope(dataset).with_next(
                 &format!("/datasets/{}/probesets", path_segment(&not_found_name)),
@@ -140,14 +131,9 @@ pub async fn dataset_probesets(
         .with_request_id(rid.clone())
     })?
     .map_err(|e| match e {
-        DatasetAuthError::Db(e) => ApiError::new(
-            StatusCode::INTERNAL_SERVER_ERROR,
-            "database_error",
-            "Database error",
-            e.to_string(),
-            "dataset_probesets",
-        )
-        .with_request_id(rid.clone()),
+        DatasetAuthError::Db(e) => {
+            ApiError::from_db(e, "dataset_probesets").with_request_id(rid.clone())
+        }
         DatasetAuthError::Auth(e) => ApiError::new(
             StatusCode::BAD_GATEWAY,
             "auth_server_error",
@@ -202,12 +188,12 @@ enum DatasetProbesetLookup<T> {
 /// Either a database error, or a failure to reach/parse gn-auth's
 /// answer while checking authorization for a non-public dataset.
 enum DatasetAuthError {
-    Db(mysql::Error),
+    Db(db::DbError),
     Auth(String),
 }
 
-impl From<mysql::Error> for DatasetAuthError {
-    fn from(e: mysql::Error) -> Self {
+impl From<db::DbError> for DatasetAuthError {
+    fn from(e: db::DbError) -> Self {
         DatasetAuthError::Db(e)
     }
 }
@@ -277,14 +263,9 @@ pub async fn dataset_probeset_info(
             .with_request_id(rid.clone())
         })?
         .map_err(|e| match e {
-            DatasetAuthError::Db(e) => ApiError::new(
-                StatusCode::INTERNAL_SERVER_ERROR,
-                "database_error",
-                "Database error",
-                e.to_string(),
-                "dataset_probeset_info",
-            )
-            .with_request_id(rid.clone()),
+            DatasetAuthError::Db(e) => {
+                ApiError::from_db(e, "dataset_probeset_info").with_request_id(rid.clone())
+            }
             DatasetAuthError::Auth(e) => ApiError::new(
                 StatusCode::BAD_GATEWAY,
                 "auth_server_error",
@@ -404,14 +385,9 @@ pub async fn dataset_probeset_values(
             .with_request_id(rid.clone())
         })?
         .map_err(|e| match e {
-            DatasetAuthError::Db(e) => ApiError::new(
-                StatusCode::INTERNAL_SERVER_ERROR,
-                "database_error",
-                "Database error",
-                e.to_string(),
-                "dataset_probeset_values",
-            )
-            .with_request_id(rid.clone()),
+            DatasetAuthError::Db(e) => {
+                ApiError::from_db(e, "dataset_probeset_values").with_request_id(rid.clone())
+            }
             DatasetAuthError::Auth(e) => ApiError::new(
                 StatusCode::BAD_GATEWAY,
                 "auth_server_error",
diff --git a/src/routes/groups.rs b/src/routes/groups.rs
index 1c87cdd..b43fb31 100644
--- a/src/routes/groups.rs
+++ b/src/routes/groups.rs
@@ -81,16 +81,7 @@ pub async fn groups(
                 "The species the groups belong to (filter groups with ?species=<name>)",
             ))
         })
-        .map_err(|e| {
-            ApiError::new(
-                StatusCode::INTERNAL_SERVER_ERROR,
-                "database_error",
-                "Database error",
-                e.to_string(),
-                "groups",
-            )
-            .with_request_id(rid)
-        })
+        .map_err(|e| ApiError::from_db(e, "groups").with_request_id(rid))
 }
 
 #[utoipa::path(get, path = "/groups/{group}", summary = "Get one group's full record by name or numeric id", params(
@@ -121,16 +112,7 @@ pub async fn group_by_name(
             )
             .with_request_id(rid.clone())
         })?
-        .map_err(|e| {
-            ApiError::new(
-                StatusCode::INTERNAL_SERVER_ERROR,
-                "database_error",
-                "Database error",
-                e.to_string(),
-                "group_by_name",
-            )
-            .with_request_id(rid.clone())
-        })?
+        .map_err(|e| ApiError::from_db(e, "group_by_name").with_request_id(rid.clone()))?
         .map(|detail| {
             let name = path_segment(&detail.name);
             Json(
@@ -204,16 +186,7 @@ pub async fn group_strains(
         )
         .with_request_id(rid.clone())
     })?
-    .map_err(|e| {
-        ApiError::new(
-            StatusCode::INTERNAL_SERVER_ERROR,
-            "database_error",
-            "Database error",
-            e.to_string(),
-            "group_strains",
-        )
-        .with_request_id(rid.clone())
-    })?
+    .map_err(|e| ApiError::from_db(e, "group_strains").with_request_id(rid.clone()))?
     .map(|strains| {
         let group = path_segment(&not_found_name);
         Json(
@@ -255,12 +228,12 @@ enum GroupTraitLookup<T> {
 /// Either a database error, or a failure to reach/parse gn-auth's
 /// answer while checking authorization for a non-public group.
 enum GroupAuthError {
-    Db(mysql::Error),
+    Db(db::DbError),
     Auth(String),
 }
 
-impl From<mysql::Error> for GroupAuthError {
-    fn from(e: mysql::Error) -> Self {
+impl From<db::DbError> for GroupAuthError {
+    fn from(e: db::DbError) -> Self {
         GroupAuthError::Db(e)
     }
 }
@@ -350,14 +323,9 @@ pub async fn group_trait_values(
         .with_request_id(rid.clone())
     })?
     .map_err(|e| match e {
-        GroupAuthError::Db(e) => ApiError::new(
-            StatusCode::INTERNAL_SERVER_ERROR,
-            "database_error",
-            "Database error",
-            e.to_string(),
-            "group_trait_values",
-        )
-        .with_request_id(rid.clone()),
+        GroupAuthError::Db(e) => {
+            ApiError::from_db(e, "group_trait_values").with_request_id(rid.clone())
+        }
         GroupAuthError::Auth(e) => ApiError::new(
             StatusCode::BAD_GATEWAY,
             "auth_server_error",
@@ -462,14 +430,9 @@ pub async fn group_trait_info(
         .with_request_id(rid.clone())
     })?
     .map_err(|e| match e {
-        GroupAuthError::Db(e) => ApiError::new(
-            StatusCode::INTERNAL_SERVER_ERROR,
-            "database_error",
-            "Database error",
-            e.to_string(),
-            "group_trait_info",
-        )
-        .with_request_id(rid.clone()),
+        GroupAuthError::Db(e) => {
+            ApiError::from_db(e, "group_trait_info").with_request_id(rid.clone())
+        }
         GroupAuthError::Auth(e) => ApiError::new(
             StatusCode::BAD_GATEWAY,
             "auth_server_error",
@@ -604,14 +567,7 @@ pub async fn group_traits(
         .with_request_id(rid.clone())
     })?
     .map_err(|e| match e {
-        GroupAuthError::Db(e) => ApiError::new(
-            StatusCode::INTERNAL_SERVER_ERROR,
-            "database_error",
-            "Database error",
-            e.to_string(),
-            "group_traits",
-        )
-        .with_request_id(rid.clone()),
+        GroupAuthError::Db(e) => ApiError::from_db(e, "group_traits").with_request_id(rid.clone()),
         GroupAuthError::Auth(e) => ApiError::new(
             StatusCode::BAD_GATEWAY,
             "auth_server_error",
@@ -686,16 +642,7 @@ pub async fn group_case_attributes(
         )
         .with_request_id(rid.clone())
     })?
-    .map_err(|e| {
-        ApiError::new(
-            StatusCode::INTERNAL_SERVER_ERROR,
-            "database_error",
-            "Database error",
-            e.to_string(),
-            "group_case_attributes",
-        )
-        .with_request_id(rid.clone())
-    })?
+    .map_err(|e| ApiError::from_db(e, "group_case_attributes").with_request_id(rid.clone()))?
     .map(|case_attributes| {
         Json(ctx.envelope(case_attributes).with_next(
             &format!("/groups/{}/strains", path_segment(&not_found_name)),
@@ -748,16 +695,7 @@ pub async fn group_datasets(
         )
         .with_request_id(rid.clone())
     })?
-    .map_err(|e| {
-        ApiError::new(
-            StatusCode::INTERNAL_SERVER_ERROR,
-            "database_error",
-            "Database error",
-            e.to_string(),
-            "group_datasets",
-        )
-        .with_request_id(rid.clone())
-    })?
+    .map_err(|e| ApiError::from_db(e, "group_datasets").with_request_id(rid.clone()))?
     .map(|datasets| {
         Json(ctx.envelope(datasets).with_next(
             &format!("/groups/{}", path_segment(&not_found_name)),
diff --git a/src/routes/mapping_methods.rs b/src/routes/mapping_methods.rs
index 224d90f..96bd49d 100644
--- a/src/routes/mapping_methods.rs
+++ b/src/routes/mapping_methods.rs
@@ -39,14 +39,5 @@ pub async fn mapping_methods(
                 "Groups, each with the mapping tool offered for it (`mapping_method`)",
             ))
         })
-        .map_err(|e| {
-            ApiError::new(
-                StatusCode::INTERNAL_SERVER_ERROR,
-                "database_error",
-                "Database error",
-                e.to_string(),
-                "mapping_methods",
-            )
-            .with_request_id(rid)
-        })
+        .map_err(|e| ApiError::from_db(e, "mapping_methods").with_request_id(rid))
 }
diff --git a/src/routes/publications.rs b/src/routes/publications.rs
index 850f934..635486a 100644
--- a/src/routes/publications.rs
+++ b/src/routes/publications.rs
@@ -18,12 +18,12 @@ enum PublicationTraits {
 }
 
 enum LookupError {
-    Db(mysql::Error),
+    Db(db::DbError),
     Auth(String),
 }
 
-impl From<mysql::Error> for LookupError {
-    fn from(e: mysql::Error) -> Self {
+impl From<db::DbError> for LookupError {
+    fn from(e: db::DbError) -> Self {
         LookupError::Db(e)
     }
 }
@@ -102,14 +102,9 @@ pub async fn publication_traits(
         .with_request_id(rid.clone())
     })?
     .map_err(|e| match e {
-        LookupError::Db(e) => ApiError::new(
-            StatusCode::INTERNAL_SERVER_ERROR,
-            "database_error",
-            "Database error",
-            e.to_string(),
-            "publication_traits",
-        )
-        .with_request_id(rid.clone()),
+        LookupError::Db(e) => {
+            ApiError::from_db(e, "publication_traits").with_request_id(rid.clone())
+        }
         LookupError::Auth(e) => ApiError::new(
             StatusCode::BAD_GATEWAY,
             "auth_server_error",
diff --git a/src/routes/species.rs b/src/routes/species.rs
index 94f8736..4214f02 100644
--- a/src/routes/species.rs
+++ b/src/routes/species.rs
@@ -42,16 +42,7 @@ pub async fn species(
                 "Groups (populations); add ?species=<name> to list one species' groups",
             ))
         })
-        .map_err(|e| {
-            ApiError::new(
-                StatusCode::INTERNAL_SERVER_ERROR,
-                "database_error",
-                "Database error",
-                e.to_string(),
-                "species",
-            )
-            .with_request_id(rid)
-        })
+        .map_err(|e| ApiError::from_db(e, "species").with_request_id(rid))
 }
 
 #[utoipa::path(get, path = "/species/{species}", summary = "Get one species' full record by name", params(
@@ -82,16 +73,7 @@ pub async fn species_by_name(
             )
             .with_request_id(rid.clone())
         })?
-        .map_err(|e| {
-            ApiError::new(
-                StatusCode::INTERNAL_SERVER_ERROR,
-                "database_error",
-                "Database error",
-                e.to_string(),
-                "species_by_name",
-            )
-            .with_request_id(rid.clone())
-        })?
+        .map_err(|e| ApiError::from_db(e, "species_by_name").with_request_id(rid.clone()))?
         .map(|detail| {
             let name = path_segment(&detail.name);
             Json(
@@ -149,16 +131,7 @@ pub async fn species_datasets(
         )
         .with_request_id(rid.clone())
     })?
-    .map_err(|e| {
-        ApiError::new(
-            StatusCode::INTERNAL_SERVER_ERROR,
-            "database_error",
-            "Database error",
-            e.to_string(),
-            "species_datasets",
-        )
-        .with_request_id(rid.clone())
-    })?
+    .map_err(|e| ApiError::from_db(e, "species_datasets").with_request_id(rid.clone()))?
     .map(|datasets| {
         Json(ctx.envelope(datasets).with_next(
             &format!("/species/{}", path_segment(&not_found_name)),
diff --git a/src/routes/traits.rs b/src/routes/traits.rs
index 0b7e77c..1ceb752 100644
--- a/src/routes/traits.rs
+++ b/src/routes/traits.rs
@@ -43,12 +43,12 @@ pub enum TraitInfoResponse {
 /// matching this codebase's existing per-module lookup/error types
 /// (see e.g. GroupTraitLookup vs DatasetProbesetLookup).
 enum TraitAuthError {
-    Db(mysql::Error),
+    Db(db::DbError),
     Auth(String),
 }
 
-impl From<mysql::Error> for TraitAuthError {
-    fn from(e: mysql::Error) -> Self {
+impl From<db::DbError> for TraitAuthError {
+    fn from(e: db::DbError) -> Self {
         TraitAuthError::Db(e)
     }
 }
@@ -147,14 +147,9 @@ pub async fn traits(
             .with_request_id(rid.clone())
         })?
         .map_err(|e| match e {
-            TraitAuthError::Db(e) => ApiError::new(
-                StatusCode::INTERNAL_SERVER_ERROR,
-                "database_error",
-                "Database error",
-                e.to_string(),
-                "traits",
-            )
-            .with_request_id(rid.clone()),
+            TraitAuthError::Db(e) => {
+                ApiError::from_db(e, "traits").with_request_id(rid.clone())
+            }
             TraitAuthError::Auth(e) => ApiError::new(
                 StatusCode::BAD_GATEWAY,
                 "auth_server_error",
@@ -294,14 +289,7 @@ pub async fn trait_info(
         .with_request_id(rid.clone())
     })?
     .map_err(|e| match e {
-        TraitAuthError::Db(e) => ApiError::new(
-            StatusCode::INTERNAL_SERVER_ERROR,
-            "database_error",
-            "Database error",
-            e.to_string(),
-            "trait_info",
-        )
-        .with_request_id(rid.clone()),
+        TraitAuthError::Db(e) => ApiError::from_db(e, "trait_info").with_request_id(rid.clone()),
         TraitAuthError::Auth(e) => ApiError::new(
             StatusCode::BAD_GATEWAY,
             "auth_server_error",
@@ -473,14 +461,7 @@ pub async fn trait_values(
         .with_request_id(rid.clone())
     })?
     .map_err(|e| match e {
-        TraitAuthError::Db(e) => ApiError::new(
-            StatusCode::INTERNAL_SERVER_ERROR,
-            "database_error",
-            "Database error",
-            e.to_string(),
-            "trait_values",
-        )
-        .with_request_id(rid.clone()),
+        TraitAuthError::Db(e) => ApiError::from_db(e, "trait_values").with_request_id(rid.clone()),
         TraitAuthError::Auth(e) => ApiError::new(
             StatusCode::BAD_GATEWAY,
             "auth_server_error",