The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
TypeScript analyticsbibusiness-intelligencebusinessintelligenceclojuredashboarddatadata-analysisdata-visualizationdatabasemetabasemysqlpostgrespostgresqlreportingslacksql-editorvisualization
Add mechanism for more reliably renaming settings (#71088)
Chris Truter213b1b5905eb
diff --git a/.clj-kondo/config.edn b/.clj-kondo/config.ednindex 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.ednindex 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.cljindex 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_' prefixExample: 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.cljindex 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.cljindex e8a0a378076..31107844245 100644--- a/src/metabase/settings/core.clj+++ b/src/metabase/settings/core.clj@@ -94,10 +94,12 @@default-valuedefsettingdisabled-for-db-reasons+ env-var-nameenv-var-valueexport?getget-raw-value+ log-deprecated-env-var-usage!get-value-of-typehas-advanced-setting-access?migrate-encrypted-settings!diff --git a/src/metabase/settings/models/setting.clj b/src/metabase/settings/models/setting.cljindex 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 notlegal 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`. Seedocstring 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 wasdiff --git a/test/metabase/cmd/env_var_dox_test.clj b/test/metabase/cmd/env_var_dox_test.cljindex 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.cljindex 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)))))