Skip to content

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

docs - filter out read-only settings for config (#78970)

Jeff Bruemmeredae5380bb1a
diff --git a/src/metabase/cmd/config_file_gen.clj b/src/metabase/cmd/config_file_gen.clj
index 29a67fa18b9..306c3abd90e 100644
--- a/src/metabase/cmd/config_file_gen.clj
+++ b/src/metabase/cmd/config_file_gen.clj
@@ -18,12 +18,20 @@
[settings]
(reduce (fn [settings k] (assoc settings k nil)) settings settings-to-reset))
+(defn config-file-settings
+ "Filters settings down to those that are valid in a config file template. We include deprecated
+ settings in the env var docs, but we exclude them from the config file template. We likewise
+ exclude read-only (`:setter :none`) settings: the config file sets settings via the same path as
+ the Admin settings, so it can never set them."
+ [settings]
+ (->> settings
+ dox/remove-env-vars-we-should-not-document
+ (filter dox/settable-in-config-file?)))
+
(defn settings
- "Gets valid config settings. We include deprecated settings in the env var docs,
- but we exclude them from the config file template."
+ "Gets valid config settings."
[]
- (->> (dox/get-settings)
- dox/remove-env-vars-we-should-not-document))
+ (config-file-settings (dox/get-settings)))
(defn get-name-and-default
"Get a setting's name and its default."
diff --git a/src/metabase/cmd/env_var_dox.clj b/src/metabase/cmd/env_var_dox.clj
index 08da4e9c270..fcdedbbea71 100644
--- a/src/metabase/cmd/env_var_dox.clj
+++ b/src/metabase/cmd/env_var_dox.clj
@@ -123,11 +123,25 @@
(when (string? d)
d)))
+(defn settable-in-config-file?
+ "Can this setting be set via the `settings:` section of a configuration file?
+ Settings with `:setter` `:none` are read-only: the config file calls the same `setting/set!` path as
+ the Admin settings, so it will always reject them."
+ [env-var]
+ (not= :none (:setter env-var)))
+
(defn- format-config-name
- "Formats the configuration file name for an environment variable."
+ "Formats the configuration file name for an environment variable, or notes that the setting is
+ read-only and can only be set with an environment variable."
[env-var]
- (if (= (:visibility env-var) :internal)
+ (cond
+ (not (settable-in-config-file? env-var))
+ "Environment variable only: you can't set this in the Admin settings or in a [configuration file](./config-file.md)."
+
+ (= (:visibility env-var) :internal)
""
+
+ :else
(str "[Configuration file name](./config-file.md): `" (:munged-name env-var) "`")))
(defn- list-item
@@ -175,7 +189,7 @@
(contains? env-vars-not-to-mess-with (format-prefix env-var))))
(defn- setter-none?
- "Used to remove settings that lack a setter (`:setter :none`).
+ "Used to remove undocumented settings that lack a setter (`:setter :none`).
For example, settings that are derived from other settings."
[env-var]
;; If the `defsetting` has a `:doc` key with a string, we should document it.
diff --git a/test/metabase/cmd/config_file_gen_test.clj b/test/metabase/cmd/config_file_gen_test.clj
index 1fbbafdc4db..4190af50e0f 100644
--- a/test/metabase/cmd/config_file_gen_test.clj
+++ b/test/metabase/cmd/config_file_gen_test.clj
@@ -1,7 +1,7 @@
(ns metabase.cmd.config-file-gen-test
(:require
[clojure.test :refer :all]
- [metabase.cmd.config-file-gen :refer [create-settings-map]]))
+ [metabase.cmd.config-file-gen :refer [config-file-settings create-settings-map]]))
(def example-settings '({:database-local :never,
:cache? true,
@@ -85,6 +85,33 @@
:munged-name "deprecated-setting",
:visibility :public}))
+(def ^:private read-only-setting
+ "A read-only (`:setter :none`) setting that also carries a `:doc` string, like
+ `ai-usage-max-retention-days`. It can be read from an environment variable, so it belongs in the
+ env var docs, but a config file can never set it."
+ {:database-local :never,
+ :cache? true,
+ :user-local :never,
+ :init nil,
+ :default nil,
+ :name :ai-usage-max-retention-days,
+ :export? true,
+ :type :integer,
+ :enabled? nil,
+ :encryption :no,
+ :deprecated nil,
+ :audit :never,
+ :sensitive? false,
+ :tag java.lang.Long,
+ :on-change nil,
+ :setter :none,
+ :doc
+ "Sets the maximum number of days Metabase preserves rows for the following application database tables:\n\n- `ai_usage_log`",
+ :feature nil,
+ :namespace 'metabase.metabot.settings,
+ :munged-name "ai-usage-max-retention-days",
+ :visibility :admin})
+
(def settings-map
{:admin-email nil
:aggregated-query-row-limit nil
@@ -95,3 +122,15 @@
(let [settings (create-settings-map example-settings)]
(is (= settings-map
settings)))))
+
+(deftest config-file-settings-excludes-read-only-settings-test
+ (testing "Read-only settings are excluded from the config file template, even when they have a `:doc`"
+ (let [names (->> (conj (vec example-settings) read-only-setting)
+ config-file-settings
+ (map :munged-name)
+ set)]
+ (is (not (contains? names "ai-usage-max-retention-days"))
+ "a `:setter :none` setting must never be offered as a config file setting")
+ (testing "and settable settings are still included"
+ (is (contains? names "admin-email"))
+ (is (contains? names "aggregated-query-row-limit"))))))
diff --git a/test/metabase/cmd/env_var_dox_test.clj b/test/metabase/cmd/env_var_dox_test.clj
index b976914f0cf..c67a0adbd4c 100644
--- a/test/metabase/cmd/env_var_dox_test.clj
+++ b/test/metabase/cmd/env_var_dox_test.clj
@@ -75,6 +75,35 @@
(testing "returns nil when doc key is missing"
(is (nil? (#'sut/format-doc {}))))))
+(deftest ^:parallel settable-in-config-file?-test
+ (testing "Read-only settings can't be set in a config file"
+ (is (false? (sut/settable-in-config-file? {:setter :none}))))
+ (testing "Settings with a setter can"
+ (is (true? (sut/settable-in-config-file? {:setter (fn [_])})))
+ (is (true? (sut/settable-in-config-file? {})))))
+
+(def ^:private env-var-only-note
+ "Environment variable only: you can't set this in the Admin settings or in a [configuration file](./config-file.md).")
+
+(deftest ^:parallel format-config-name-test
+ (testing "Read-only settings are flagged as environment-variable-only, whatever their visibility"
+ (is (= env-var-only-note
+ (#'sut/format-config-name {:munged-name "show-google-sheets-integration"
+ :setter :none
+ :visibility :public})))
+ (testing "including internal ones, which otherwise get no line at all"
+ (is (= env-var-only-note
+ (#'sut/format-config-name {:munged-name "audit-max-retention-days"
+ :setter :none
+ :visibility :internal})))))
+ (testing "Internal settings with a setter get no config file line"
+ (is (= "" (#'sut/format-config-name {:munged-name "internal-setting"
+ :visibility :internal}))))
+ (testing "Settable, non-internal settings get their config file name"
+ (is (= "[Configuration file name](./config-file.md): `admin-email`"
+ (#'sut/format-config-name {:munged-name "admin-email"
+ :visibility :authenticated})))))
+
(deftest ^:parallel format-env-var-entry-with-false-doc-test
(testing "format-env-var-entry doesn't crash when env-var has :doc false"
(let [env-var-with-false-doc {:name :test-setting