metabase.models.setting — metabase-core 1.0.0-SNAPSHOT

Settings are a fast and simple way to create a setting that can be set from the admin page. They are saved to the Database, but intelligently cached internally for super-fast lookups.

Define a new Setting with defsetting (optionally supplying a default value, type, or custom getters & setters):

(defsetting mandrill-api-key "API key for Mandrill")

The setting and docstr will then be auto-magically accessible from the admin page.

You can also set the value via the corresponding env var, which looks like MB_MANDRILL_API_KEY, where the name of the setting is converted to uppercase and dashes to underscores.

The var created with defsetting can be used as a getter/setter, or you can use get and set!:

(require '[metabase.models.setting :as setting])

(setting/get :mandrill-api-key)           ; only returns values set explicitly from SuperAdmin
(mandrill-api-key)                        ; returns value set in SuperAdmin, OR value of corresponding env var,
                                          ; OR the default value, if any (in that order)

(setting/set! :mandrill-api-key "NEW_KEY")
(mandrill-api-key "NEW_KEY")

(setting/set! :mandrill-api-key nil)
(mandrill-api-key nil)

Get a map of all Settings:

(setting/all)

all clj

(all & {:as options})

Return a sequence of Settings maps in a format suitable for consumption by the frontend. (For security purposes, this doesn't return the value of a Setting if it was set via env var).

options are passed to user-facing-value.

defsetting clj macro

(defsetting setting-symb description & {:as options})

Defines a new Setting that will be added to the DB at some point in the future. Conveniently can be used as a getter/setter as well:

(defsetting mandrill-api-key "API key for Mandrill.") (mandrill-api-key) ; get the value (mandrill-api-key new-value) ; update the value (mandrill-api-key nil) ; delete the value

A setting can be set from the SuperAdmin page or via the corresponding env var, eg. MB_MANDRILL_API_KEY for the example above.

You may optionally pass any of the OPTIONS below:

• :default - The default value of the setting. (default: nil)

• :type - :string (default), :boolean, :integer, :json, :double, or :timestamp. Non-:string Settings have special default getters and setters that automatically coerce values to the correct types.

• :internal? - This Setting is for internal use and shouldn't be exposed in the UI (i.e., not returned by the corresponding endpoints). Default: false

• :getter - A custom getter fn, which takes no arguments. Overrides the default implementation. (This can in turn call functions in this namespace like get-string or get-boolean to invoke the default getter behavior.)

• :setter - A custom setter fn, which takes a single argument. Overrides the default implementation. (This can in turn call functions in this namespace like set-string! or set-boolean! to invoke the default setter behavior. Keep in mind that the custom setter may be passed nil, which should clear the values of the Setting.)

• :cache? - Should this Setting be cached? (default true)? Be careful when disabling this, because it could have a very negative performance impact.

• :sensitive? - Is this a sensitive setting, such as a password, that we should never return in plaintext? (Default: false). Obfuscation is not done by getter functions, but instead by functions that ultimately return these values via the API, such as all below. (In other words, code in the backend can continute to consume sensitive Settings normally; sensitivity is a purely user-facing option.)

env-var-value clj

(env-var-value setting-or-name)

Get the value of setting-or-name from the corresponding env var, if any. 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.

get clj

(get setting-or-name)

Fetch the value of setting-or-name. What this means depends on the Setting's :getter; by default, this looks for first for a corresponding env var, then checks the cache, then returns the default value of the Setting, if any.

get-boolean clj

(get-boolean setting-or-name)

Get boolean value of (presumably :boolean) setting-or-name. This is the default getter for :boolean settings. Returns one of the following values:

• nil if string value of setting-or-name is unset (or empty)
• true if lowercased string value of setting-or-name is true
• false if lowercased string value of setting-or-name is false.

get-csv clj

(get-csv setting-or-name)

Get the string value of setting-or-name and parse it as CSV, returning a sequence of exploded strings.

get-double clj

(get-double setting-or-name)

Get double value of (presumably :double) setting-or-name. This is the default getter for :double settings.

get-integer clj

(get-integer setting-or-name)

Get integer value of (presumably :integer) setting-or-name. This is the default getter for :integer settings.

get-json clj

(get-json setting-or-name)

Get the string value of setting-or-name and parse it as JSON.

get-string clj

(get-string setting-or-name)

Get string value of setting-or-name. This is the default getter for String settings; value is fetched as follows:

1. From the database (i.e., set via the admin panel), if a value is present;
2. From corresponding env var, if any;
3. The default value, if one was specified.

If the fetched value is an empty string it is considered to be unset and this function returns nil.

get-timestamp clj

(get-timestamp setting-or-name)

Get the string value of setting-or-name and parse it as an ISO-8601-formatted string, returning a Timestamp.

metadata-for-setting-fn clj

(metadata-for-setting-fn
  {:keys [default description tag] setting-type :type :as setting})

Create metadata for the function automatically generated by defsetting.

register-setting! clj

(register-setting!
  {setting-name :name setting-type :type default :default :as setting})

Register a new Setting with a map of SettingDefinition attributes. This is used internally be defsetting; you shouldn't need to use it yourself.

set! clj

(set! setting-or-name new-value)

Set the value of setting-or-name. What this means depends on the Setting's :setter; by default, this just updates the Settings cache and writes its value to the DB.

(set :mandrill-api-key "xyz123")

Style note: prefer using the setting directly instead:

(mandrill-api-key "xyz123")

set-boolean! clj

(set-boolean! setting-or-name new-value)

Set the value of boolean setting-or-name. new-value can be nil, a boolean, or a string representation of one, such as "true" or "false" (these strings are case-insensitive).

set-csv! clj

(set-csv! setting-or-name new-value)

Serialize new-value for setting-or-name as a CSV-encoded string and save it.

set-double! clj

(set-double! setting-or-name new-value)

Set the value of double setting-or-name.

set-integer! clj

(set-integer! setting-or-name new-value)

Set the value of integer setting-or-name.

set-json! clj

(set-json! setting-or-name new-value)

Serialize new-value for setting-or-name as a JSON string and save it.

set-many! clj

(set-many! settings)

Set the value of several Settings at once.

(set-all {:mandrill-api-key "xyz123", :another-setting "ABC"})

set-string! clj

(set-string! setting-or-name new-value)

Inputs: [setting-or-name new-value :- (s/maybe s/Str)]

Set string value of setting-or-name. A nil or empty new-value can be passed to unset (i.e., delete) setting-or-name. String-type settings use this function directly; all other types ultimately call this (e.g. set-boolean! eventually calls set-string!). Returns the new-value.

set-timestamp! clj

(set-timestamp! setting-or-name new-value)

Serialize new-value for setting-or-name as a ISO 8601-encoded timestamp string and save it.

Setting clj

(Setting)

(Setting id)

(Setting & kvs)

The model that underlies defsetting.

setting-fn clj

(setting-fn setting)

Create the automatically defined getter/setter function for settings defined by defsetting.

user-facing-value clj

(user-facing-value setting-or-name & {:keys [getter] :or {getter get}})

Get the value of a Setting that should be displayed to a User (i.e. via /api/setting/ endpoints): for Settings set via env vars, or Settings whose value has not been set (i.e., Settings whose value is the same as the default value) no value is displayed; for sensitive Settings, the value is obfuscated.

Accepts options:

• :getter -- the getter function to use to fetch the Setting value. By default, uses setting/get, which will convert the setting to the appropriate type; you can use get-string to get all string values of Settings, for example.