Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

Add mechanism for more reliably renaming settings (#71088)

Chris Truter213b1b5905eb
diff --git a/.clj-kondo/config.edn b/.clj-kondo/config.edn
index 08727d8db1b..f0fedddd84a 100644
--- a/.clj-kondo/config.edn
+++ b/.clj-kondo/config.edn
@@ -793,7 +793,7 @@
:private-call {:level :off}
:metabase/defsetting-must-specify-export {:level :off}
:metabase/defsetting-namespace {:level :off}
- :metabase/test-helpers-use-non-thread-safe-functions {:level :warning} ; more config in `.clj-kondo/config/test-helpers/config.edn
+ :metabase/test-helpers-use-non-thread-safe-functions {:level :warning} ; more config in `.clj-kondo/config/test-helpers/config.edn`
:discouraged-var
{metabase.driver/database-supports? {:level :off}
diff --git a/.clj-kondo/config/test-helpers/config.edn b/.clj-kondo/config/test-helpers/config.edn
index 1f00da69396..a1befed6ee1 100644
--- a/.clj-kondo/config/test-helpers/config.edn
+++ b/.clj-kondo/config/test-helpers/config.edn
@@ -110,6 +110,7 @@
metabase.settings.models.setting-test/test-user-local-allowed-setting!
metabase.settings.models.setting-test/test-user-local-only-setting!
metabase.settings.models.setting.cache/restore-cache!
+ metabase.settings.models.setting/log-deprecated-env-var-usage!
metabase.settings.models.setting/set!
metabase.settings.models.setting/validate-settings-formatting!
metabase.setup.core/create-token!
diff --git a/src/metabase/cmd/env_var_dox.clj b/src/metabase/cmd/env_var_dox.clj
index cf0bb3293e5..f43c175113a 100644
--- a/src/metabase/cmd/env_var_dox.clj
+++ b/src/metabase/cmd/env_var_dox.clj
@@ -69,7 +69,7 @@
"Formats an environment variable name with the 'MB_' prefix
Example: MB_ENV_VAR_NAME or MB_OLD_SETTING [DEPRECATED]"
[env-var]
- (let [base-name (str "MB_" (u/->SCREAMING_SNAKE_CASE_EN (:munged-name env-var)))]
+ (let [base-name (setting/env-var-name (:name env-var))]
(if (:deprecated env-var)
(str base-name " [DEPRECATED]")
base-name)))
diff --git a/src/metabase/core/core.clj b/src/metabase/core/core.clj
index a5ece044260..933da7d946a 100644
--- a/src/metabase/core/core.clj
+++ b/src/metabase/core/core.clj
@@ -226,6 +226,7 @@
(setting/migrate-encrypted-settings!)
(database/check-health!)
(startup/run-startup-logic!)
+ (setting/log-deprecated-env-var-usage!)
(init-status/set-progress! 0.95)
(task/start-scheduler!)
(queue/start-listeners!)
diff --git a/src/metabase/settings/core.clj b/src/metabase/settings/core.clj
index e8a0a378076..31107844245 100644
--- a/src/metabase/settings/core.clj
+++ b/src/metabase/settings/core.clj
@@ -94,10 +94,12 @@
default-value
defsetting
disabled-for-db-reasons
+ env-var-name
env-var-value
export?
get
get-raw-value
+ log-deprecated-env-var-usage!
get-value-of-type
has-advanced-setting-access?
migrate-encrypted-settings!
diff --git a/src/metabase/settings/models/setting.clj b/src/metabase/settings/models/setting.clj
index 10e59030aae..7a76c855772 100644
--- a/src/metabase/settings/models/setting.clj
+++ b/src/metabase/settings/models/setting.clj
@@ -276,7 +276,11 @@
;; display rules - for example, giving certain reasons higher precedence.
;;
;; This is only valid for database-local settings.
- [:enabled-for-db? [:maybe ifn?]]])
+ [:enabled-for-db? [:maybe ifn?]]
+
+ ;; A previous name for this setting whose env var (e.g. MB_OLD_NAME) is checked
+ ;; as a fallback when the primary env var is not set. Logs a warning when used.
+ [:deprecated-name [:maybe :keyword]]])
(defonce ^{:doc "Map of loaded defsettings"}
registered-settings
@@ -439,7 +443,7 @@
[setting-nm]
(str/replace (name setting-nm) #"[^a-zA-Z0-9_-]*" ""))
-(defn- env-var-name
+(defn env-var-name
"Get the env var corresponding to `setting-definition-or-name`. (This is used primarily for documentation purposes)."
^String [setting-definition-or-name]
(str "MB_" (-> (setting-name setting-definition-or-name)
@@ -463,14 +467,47 @@
The name of the Setting is converted to uppercase and dashes to underscores; for example, a setting named
`default-domain` can be set with the env var `MB_DEFAULT_DOMAIN`. Note that this strips out characters that are not
legal for shells. Setting `foo-bar?` will expect to find the key `:mb-foo-bar` which will be sourced from the
- environment variable `MB_FOO_BAR`."
+ environment variable `MB_FOO_BAR`.
+
+ When the primary env var is truly absent (nil from environ) and the setting has a `:deprecated-name`, the env var
+ derived from that name is checked as a fallback. An empty string for the primary env var means \"explicitly unset\"
+ and blocks the fallback."
^String [setting-definition-or-name]
(let [setting (resolve-setting setting-definition-or-name)]
(when (and (allows-site-wide-values? setting)
(allows-setting-via-env? setting))
- (let [v (env/env (setting-env-map-name setting))]
- (when (seq v)
- v)))))
+ (if-let [v (env/env (setting-env-map-name setting))]
+ ;; primary env var is set — return it only if non-empty
+ (not-empty v)
+ ;; primary env var is absent — try deprecated name
+ (when-let [deprecated-name (:deprecated-name setting)]
+ (not-empty (env/env (setting-env-map-name deprecated-name))))))))
+
+(defn log-deprecated-env-var-usage!
+ "Log warnings for any settings currently using a deprecated env var name.
+ Should be called during startup after all settings are registered."
+ []
+ (doseq [[_ setting] @registered-settings
+ :when (:deprecated-name setting)
+ :when (and (allows-site-wide-values? setting)
+ (allows-setting-via-env? setting))
+ :let [legacy-v (not-empty (env/env (setting-env-map-name (:deprecated-name setting))))]
+ :when legacy-v]
+ (let [primary-env (env-var-name setting)
+ legacy-env (env-var-name (:deprecated-name setting))
+ primary-v (not-empty (env/env (setting-env-map-name setting)))]
+ (cond
+ (and primary-v (not= primary-v legacy-v))
+ (log/warnf "%s and deprecated %s have conflicting values; using %s. Remove %s."
+ primary-env legacy-env primary-env legacy-env)
+
+ primary-v
+ (log/warnf "%s and deprecated %s are both set. Remove %s."
+ primary-env legacy-env legacy-env)
+
+ :else
+ (log/warnf "Deprecated %s is set; rename it to %s."
+ legacy-env primary-env)))))
(def ^:private ^:dynamic *disable-init* false)
@@ -1052,6 +1089,7 @@
:user-local :never
:driver-feature nil
:enabled-for-db? nil
+ :deprecated-name nil
:deprecated nil
:enabled? nil
:can-read-from-env? true
@@ -1102,6 +1140,10 @@
(throw (ex-info (tru "Setting {0} uses :enabled-for-db?, but is not limited to only database-local values"
setting-name)
{:setting setting})))
+ (when (and (:deprecated-name <>) (not (:can-read-from-env? <>)))
+ (throw (ex-info (tru "Setting {0} uses :deprecated-name but has :can-read-from-env? set to false"
+ setting-name)
+ {:setting <>})))
(swap! registered-settings assoc setting-name <>))))
;;; +----------------------------------------------------------------------------------------------------------------+
@@ -1307,6 +1349,13 @@
Whether this Setting is /User-local/. Valid values are `:only`, `:allowed`, and `:never`. Default: `:never`. See
docstring for [[metabase.settings.models.setting]] for more info.
+ ###### `:deprecated-name`
+
+ A keyword naming a previous version of this setting whose env var should be checked as a fallback when the primary
+ env var is not set. For example, `:deprecated-name :my-old-setting` means `MB_MY_OLD_SETTING` will be tried when
+ `MB_MY_NEW_SETTING` is absent. A deprecation warning is logged at startup when the fallback is in use. The setting
+ must allow env var reading (`:can-read-from-env? true`, the default). (Default: `nil`).
+
###### `:deprecated`
If this setting is deprecated, this should contain a string of the Metabase version in which the setting was
diff --git a/test/metabase/cmd/env_var_dox_test.clj b/test/metabase/cmd/env_var_dox_test.clj
index ea161910a38..b976914f0cf 100644
--- a/test/metabase/cmd/env_var_dox_test.clj
+++ b/test/metabase/cmd/env_var_dox_test.clj
@@ -8,9 +8,9 @@
(deftest ^:parallel test-format-prefix
(testing "format-prefix handles deprecated variables."
- (let [normal-var {:munged-name "test-setting"}
- deprecated-var {:munged-name "old-setting" :deprecated true}
- deprecated-with-msg-var {:munged-name "very-old-setting" :deprecated "Since v0.53"}]
+ (let [normal-var {:name :test-setting}
+ deprecated-var {:name :old-setting :deprecated true}
+ deprecated-with-msg-var {:name :very-old-setting :deprecated "Since v0.53"}]
(is (= "MB_TEST_SETTING" (#'sut/format-prefix normal-var)))
(is (= "MB_OLD_SETTING [DEPRECATED]" (#'sut/format-prefix deprecated-var)))
(is (= "MB_VERY_OLD_SETTING [DEPRECATED]" (#'sut/format-prefix deprecated-with-msg-var))))))
diff --git a/test/metabase/settings/models/setting_test.clj b/test/metabase/settings/models/setting_test.clj
index a76c7ad4c0d..d16dd7265ae 100644
--- a/test/metabase/settings/models/setting_test.clj
+++ b/test/metabase/settings/models/setting_test.clj
@@ -69,6 +69,12 @@
:visibility :internal
:encryption :when-encryption-key-set)
+(defsetting test-setting-with-deprecated-name
+ "Test setting with a deprecated env var name"
+ :visibility :internal
+ :encryption :when-encryption-key-set
+ :deprecated-name :old-test-setting-name)
+
(defsetting toucan-name
"Name for the Metabase Toucan mascot."
:visibility :internal
@@ -1800,3 +1806,48 @@
(mt/with-temporary-setting-values [test-setting-that-is-not-included-when-listing-in-api "fun-times"]
(is (= ::not-present
(f :test-setting-that-is-not-included-when-listing-in-api)))))))))
+
+;;; ----------------------------------------- deprecated-name env var fallback -----------------------------------------
+
+(defn- deprecated-env-var-warnings
+ "Return warning log messages mentioning the deprecated env var after running [[setting/log-deprecated-env-var-usage!]]."
+ []
+ (mt/with-log-messages-for-level [messages :warn]
+ (setting/log-deprecated-env-var-usage!)
+ (->> (messages) (mapv :message) (filterv #(str/includes? % "OLD_TEST_SETTING")))))
+
+(deftest deprecated-name-only-legacy-set-test
+ (mt/with-temp-env-var-value! [mb-old-test-setting-name "LEGACY"]
+ (is (= "LEGACY" (setting/env-var-value :test-setting-with-deprecated-name)))
+ (is (= ["Deprecated MB_OLD_TEST_SETTING_NAME is set; rename it to MB_TEST_SETTING_WITH_DEPRECATED_NAME."]
+ (deprecated-env-var-warnings)))))
+
+(deftest deprecated-name-both-set-different-values-test
+ (mt/with-temp-env-var-value! [mb-test-setting-with-deprecated-name "PRIMARY"
+ mb-old-test-setting-name "LEGACY"]
+ (is (= "PRIMARY" (setting/env-var-value :test-setting-with-deprecated-name)))
+ (is (= [(str "MB_TEST_SETTING_WITH_DEPRECATED_NAME and deprecated MB_OLD_TEST_SETTING_NAME"
+ " have conflicting values; using MB_TEST_SETTING_WITH_DEPRECATED_NAME."
+ " Remove MB_OLD_TEST_SETTING_NAME.")]
+ (deprecated-env-var-warnings)))))
+
+(deftest deprecated-name-both-set-same-value-test
+ (mt/with-temp-env-var-value! [mb-test-setting-with-deprecated-name "SAME"
+ mb-old-test-setting-name "SAME"]
+ (is (= "SAME" (setting/env-var-value :test-setting-with-deprecated-name)))
+ (is (= ["MB_TEST_SETTING_WITH_DEPRECATED_NAME and deprecated MB_OLD_TEST_SETTING_NAME are both set. Remove MB_OLD_TEST_SETTING_NAME."]
+ (deprecated-env-var-warnings)))))
+
+(deftest deprecated-name-only-primary-set-test
+ (mt/with-temp-env-var-value! [mb-test-setting-with-deprecated-name "PRIMARY"]
+ (is (= "PRIMARY" (setting/env-var-value :test-setting-with-deprecated-name)))
+ (is (= [] (deprecated-env-var-warnings)))))
+
+(deftest deprecated-name-neither-set-test
+ (is (nil? (setting/env-var-value :test-setting-with-deprecated-name)))
+ (is (= [] (deprecated-env-var-warnings))))
+
+(deftest deprecated-name-empty-primary-blocks-fallback-test
+ (mt/with-temp-env-var-value! [mb-test-setting-with-deprecated-name ""
+ mb-old-test-setting-name "LEGACY"]
+ (is (nil? (setting/env-var-value :test-setting-with-deprecated-name)))))