Skip to content

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

Add environment variables for controlling the App DB connection pool (#74025)

metambencb91c1125a0d
diff --git a/src/metabase/app_db/connection_pool_setup.clj b/src/metabase/app_db/connection_pool_setup.clj
index f36bc24ffac..5de7e5e3749 100644
--- a/src/metabase/app_db/connection_pool_setup.clj
+++ b/src/metabase/app_db/connection_pool_setup.clj
@@ -79,11 +79,12 @@
(register-customizer! MetabaseConnectionCustomizer)
-(def ^:private application-db-connection-pool-props
+(defn- application-db-connection-pool-props
"Options for c3p0 connection pool for the application DB. These are set in code instead of the `c3p0.properties` file
because we use separate options for data warehouse DBs, and setting them in the properties file would affect both.
See https://www.mchange.com/projects/c3p0/#configuring_connection_testing for an overview of the options used
below (jump to the 'Simple advice on Connection testing' section.)"
+ []
{;;
;; If this is a number greater than 0, c3p0 will test all idle, pooled but unchecked-out connections, every this
;; number of seconds
@@ -91,7 +92,8 @@
;; https://www.mchange.com/projects/c3p0/#idleConnectionTestPeriod
;;
"idleConnectionTestPeriod"
- 60
+ (or (config/config-int :mb-application-db-idle-connection-test-period-seconds)
+ 60)
;;
;; The fully qualified class-name of an implementation of the ConnectionCustomizer interface, which users can
;; implement to set up Connections when they are acquired from the database, or on check-out, and potentially to
@@ -116,7 +118,8 @@
;; https://metaboat.slack.com/archives/C05MPF0TM3L/p1748538357522569?thread_ts=1748507464.051999&cid=C05MPF0TM3L
;;
"maxIdleTimeExcessConnections"
- (* 10 60) ; 10 minutes
+ (or (config/config-int :mb-application-db-max-idle-time-excess-connections-seconds)
+ (* 10 60)) ; 10 minutes
;;
;; Seconds, effectively a time to live. A Connection older than maxConnectionAge will be destroyed and purged from
;; the pool. This differs from maxIdleTime in that it refers to absolute age. Even a Connection which has not been
@@ -125,8 +128,22 @@
;;
;; https://www.mchange.com/projects/c3p0/#maxConnectionAge
;;
+ ;; The default of one hour can be overridden (e.g. to 0, disabling forced recycling) when using a dynamic credential
+ ;; mechanism that establishes new physical connections under tokens that would have expired by the time recycling
+ ;; happens. See https://github.com/metabase/metabase/issues/72705.
+ ;;
"maxConnectionAge"
- (* 60 60) ; one hour
+ (or (config/config-int :mb-application-db-max-connection-age-seconds)
+ (* 60 60)) ; one hour
+ ;;
+ ;; If true, an operation will be performed at every connection checkout to verify that the connection is valid. This
+ ;; adds latency to every checkout but is useful with credential schemes that may invalidate physical connections
+ ;; behind c3p0's back. Defaults to false to preserve historical behavior.
+ ;;
+ ;; https://www.mchange.com/projects/c3p0/#testConnectionOnCheckout
+ ;;
+ "testConnectionOnCheckout"
+ (boolean (config/config-bool :mb-application-db-test-connection-on-checkout))
;;
;; Maximum number of Connections a pool will maintain at any given time.
;;
@@ -138,7 +155,10 @@
15)
"unreturnedConnectionTimeout"
- (or (config/config-int :mb-application-db-unreturned-connection-timeout)
+ ;; `MB_APPLICATION_DB_UNRETURNED_CONNECTION_TIMEOUT` is the legacy unsuffixed name (its value has always been
+ ;; seconds); keep it working as a fallback alongside the new `_SECONDS` name.
+ (or (config/config-int :mb-application-db-unreturned-connection-timeout-seconds)
+ (config/config-int :mb-application-db-unreturned-connection-timeout)
;; we set an unreturnedConnectionTimeout for data warehouses, via
;; `(driver.settings/jdbc-data-warehouse-unreturned-connection-timeout-seconds)`, which defaults to the same
;; 5 minute value as the query timeout. But for the application DB this is not nearly so safe, as we don't
@@ -158,7 +178,7 @@
(if (instance? PoolBackedDataSource data-source)
data-source
(let [ds-name (format "metabase-%s-app-db" (name db-type))
- pool-props (assoc application-db-connection-pool-props "dataSourceName" ds-name)]
+ pool-props (assoc (application-db-connection-pool-props) "dataSourceName" ds-name)]
(com.mchange.v2.c3p0.DataSources/pooledDataSource
data-source
(connection-pool/map->properties pool-props)))))
diff --git a/src/metabase/cmd/resources/other-env-vars.md b/src/metabase/cmd/resources/other-env-vars.md
index 06f2f91acf0..264bf2e4a21 100644
--- a/src/metabase/cmd/resources/other-env-vars.md
+++ b/src/metabase/cmd/resources/other-env-vars.md
@@ -15,6 +15,26 @@ Use [MB_SESSION_COOKIES](#mb_session_cookies) to also expire sessions, when brow
Also see the [Changing session expiration](../people-and-groups/changing-session-expiration.md) documentation page.
+### `MB_APPLICATION_DB_IDLE_CONNECTION_TEST_PERIOD_SECONDS`
+
+Type: integer<br>
+Default: `60`<br>
+Since: v62.0
+
+How often, in seconds, to test idle connections in the application database pool. Set to `0` to disable idle connection testing.
+
+### `MB_APPLICATION_DB_MAX_CONNECTION_AGE_SECONDS`
+
+Type: integer<br>
+Default: `3600`<br>
+Since: v62.0
+
+Maximum lifetime, in seconds, of a connection in the application database pool. After this duration the connection is closed and a new one is opened. Set to `0` to keep connections until the database closes them.
+
+The default of one hour is set primarily to limit memory growth (especially on PostgreSQL).
+
+If you are connecting with a short-lived credential (e.g. an AWS RDS IAM auth token) baked into the URL or password at startup, setting this to `0` is a partial workaround — eventual reconnects from the database or the network will still fail. Prefer [MB_DB_AWS_IAM](#mb_db_aws_iam) (AWS RDS / Aurora) or [MB_DB_AZURE_MANAGED_IDENTITY_CLIENT_ID](#mb_db_azure_managed_identity_client_id) (Azure).
+
### `MB_APPLICATION_DB_MAX_CONNECTION_POOL_SIZE`
Type: integer<br>
@@ -29,6 +49,30 @@ To see how many connections are being used, check the Metabase logs and look for
See [MB_JDBC_DATA_WAREHOUSE_MAX_CONNECTION_POOL_SIZE](#mb_jdbc_data_warehouse_max_connection_pool_size) for setting maximum connections to the databases connected to Metabase.
+### `MB_APPLICATION_DB_MAX_IDLE_TIME_EXCESS_CONNECTIONS_SECONDS`
+
+Type: integer<br>
+Default: `600`<br>
+Since: v62.0
+
+How long, in seconds, an idle connection beyond the minimum pool size may stay open before being culled. Set to `0` to never cull excess idle connections.
+
+### `MB_APPLICATION_DB_TEST_CONNECTION_ON_CHECKOUT`
+
+Type: boolean<br>
+Default: `false`<br>
+Since: v62.0
+
+When `true`, each connection is validated when checked out of the pool. Adds latency to every checkout. Useful when credentials may invalidate connections behind the pool's back.
+
+### `MB_APPLICATION_DB_UNRETURNED_CONNECTION_TIMEOUT_SECONDS`
+
+Type: integer<br>
+Default: `3600`<br>
+Since: v62.0
+
+How long, in seconds, before a checked-out but unreturned connection is forcibly reclaimed. The legacy name `MB_APPLICATION_DB_UNRETURNED_CONNECTION_TIMEOUT` continues to work; the suffixed form is preferred.
+
### `MB_ASYNC_QUERY_THREAD_POOL_SIZE`
Type: integer<br>
@@ -58,6 +102,28 @@ Default: `true`
When set to `false`, Metabase will print migrations needed to be done in the application database and exit. Those migrations need to be applied manually. When `true`, Metabase will automatically make changes to the application database. This is not related to migrating away from H2.
+### `MB_DB_AWS_IAM`
+
+Type: boolean<br>
+Default: `false`<br>
+Since: v0.58.0
+
+When `true`, authenticate to the application database (PostgreSQL or MySQL/MariaDB on AWS RDS or Aurora) using AWS IAM instead of a password. Omit [MB_DB_PASS](#mb_db_pass). Auth tokens are refreshed automatically.
+
+Requires that AWS credentials are available via the standard credential chain (e.g. EKS IRSA, EC2 instance profile, ECS task role, or `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`), that the credentials hold the `rds-db:connect` permission for your database user, and that the DB user is set up for IAM authentication.
+
+For MySQL/MariaDB, also set [MB_DB_SSL_CERT](#mb_db_ssl_cert), or pass the SSL parameters in [MB_DB_CONNECTION_URI](#mb_db_connection_uri).
+
+### `MB_DB_AZURE_MANAGED_IDENTITY_CLIENT_ID`
+
+Type: string<br>
+Default: `null`<br>
+Since: v0.51.0
+
+Authenticate to a PostgreSQL or MySQL application database using an Azure Managed Identity instead of a password. Set this to the client ID of a user-assigned Managed Identity attached to your compute resource. Omit [MB_DB_PASS](#mb_db_pass). Access tokens are refreshed automatically.
+
+Requires the Database authentication providers Pro/Enterprise feature.
+
### `MB_DB_CONNECTION_URI`
Type: string<br>
@@ -121,6 +187,17 @@ Default: `null`
The port for [MB_DB_HOST](#mb_db_host).
+### `MB_DB_SSL_CERT`
+
+Type: string<br>
+Default: `null`<br>
+Since: v0.58.0
+
+SSL configuration for the application database. Used with [MB_DB_AWS_IAM](#mb_db_aws_iam) on MySQL/MariaDB, where SSL is required.
+
+- `"trust"` — trust the server certificate without validation.
+- A filesystem path to a PEM file — validate against the supplied CA certificate.
+
### `MB_DB_TYPE`
Type: string (`"h2"`, `"postgres"`, `"mysql"`)<br>
diff --git a/test/metabase/app_db/connection_pool_setup_test.clj b/test/metabase/app_db/connection_pool_setup_test.clj
index 2872c3e3c9f..349033efa47 100644
--- a/test/metabase/app_db/connection_pool_setup_test.clj
+++ b/test/metabase/app_db/connection_pool_setup_test.clj
@@ -6,6 +6,7 @@
[metabase.app-db.connection-pool-setup :as mdb.connection-pool-setup]
[metabase.app-db.core :as app-db]
[metabase.app-db.data-source :as mdb.data-source]
+ [metabase.config.core :as config]
[metabase.connection-pool :as connection-pool]
[metabase.test :as mt]
[metabase.test.fixtures :as fixtures]
@@ -99,6 +100,71 @@
(is (not (#'mdb.connection-pool-setup/recent-activity?* latest-activity (t/millis 10)))
"recent-window-duration has elapsed but still recent")))))
+(defn- with-config-overrides
+ "Returns a fn replacement for `config/config-int` (or `config/config-bool`) that returns
+ `overrides`' value for matching keys and the original config fn's value otherwise."
+ [orig-fn overrides]
+ (fn [k]
+ (if (contains? overrides k)
+ (get overrides k)
+ (orig-fn k))))
+
+(deftest application-db-connection-pool-props-defaults-test
+ (testing "default values are preserved when no overrides are set"
+ (with-redefs [config/config-int (with-config-overrides config/config-int
+ {:mb-application-db-max-connection-pool-size nil
+ :mb-application-db-unreturned-connection-timeout nil
+ :mb-application-db-unreturned-connection-timeout-seconds nil
+ :mb-application-db-max-connection-age-seconds nil
+ :mb-application-db-idle-connection-test-period-seconds nil
+ :mb-application-db-max-idle-time-excess-connections-seconds nil})
+ config/config-bool (with-config-overrides config/config-bool
+ {:mb-application-db-test-connection-on-checkout nil})]
+ (let [props (#'mdb.connection-pool-setup/application-db-connection-pool-props)]
+ (is (= 60 (get props "idleConnectionTestPeriod")))
+ (is (= 600 (get props "maxIdleTimeExcessConnections")))
+ (is (= 3600 (get props "maxConnectionAge")))
+ (is (= 15 (get props "maxPoolSize")))
+ (is (= 3600 (get props "unreturnedConnectionTimeout")))
+ (is (false? (get props "testConnectionOnCheckout")))))))
+
+(deftest application-db-connection-pool-props-overrides-test
+ (testing "MB_APPLICATION_DB_MAX_CONNECTION_AGE_SECONDS overrides maxConnectionAge"
+ (with-redefs [config/config-int (with-config-overrides config/config-int
+ {:mb-application-db-max-connection-age-seconds 0})]
+ (is (= 0 (get (#'mdb.connection-pool-setup/application-db-connection-pool-props)
+ "maxConnectionAge"))
+ "setting maxConnectionAge to 0 must be honored (use case: RDS IAM auth via the AWS JDBC wrapper)")))
+ (testing "MB_APPLICATION_DB_IDLE_CONNECTION_TEST_PERIOD_SECONDS overrides idleConnectionTestPeriod"
+ (with-redefs [config/config-int (with-config-overrides config/config-int
+ {:mb-application-db-idle-connection-test-period-seconds 30})]
+ (is (= 30 (get (#'mdb.connection-pool-setup/application-db-connection-pool-props)
+ "idleConnectionTestPeriod")))))
+ (testing "MB_APPLICATION_DB_MAX_IDLE_TIME_EXCESS_CONNECTIONS_SECONDS overrides maxIdleTimeExcessConnections"
+ (with-redefs [config/config-int (with-config-overrides config/config-int
+ {:mb-application-db-max-idle-time-excess-connections-seconds 120})]
+ (is (= 120 (get (#'mdb.connection-pool-setup/application-db-connection-pool-props)
+ "maxIdleTimeExcessConnections")))))
+ (testing "MB_APPLICATION_DB_TEST_CONNECTION_ON_CHECKOUT overrides testConnectionOnCheckout"
+ (with-redefs [config/config-bool (with-config-overrides config/config-bool
+ {:mb-application-db-test-connection-on-checkout true})]
+ (is (true? (get (#'mdb.connection-pool-setup/application-db-connection-pool-props)
+ "testConnectionOnCheckout"))))))
+
+(deftest application-db-unreturned-connection-timeout-aliasing-test
+ (testing "the _SECONDS-suffixed name takes precedence over the legacy unsuffixed name"
+ (with-redefs [config/config-int (with-config-overrides config/config-int
+ {:mb-application-db-unreturned-connection-timeout-seconds 42
+ :mb-application-db-unreturned-connection-timeout 99})]
+ (is (= 42 (get (#'mdb.connection-pool-setup/application-db-connection-pool-props)
+ "unreturnedConnectionTimeout")))))
+ (testing "the legacy unsuffixed name still works when the _SECONDS-suffixed name is not set"
+ (with-redefs [config/config-int (with-config-overrides config/config-int
+ {:mb-application-db-unreturned-connection-timeout-seconds nil
+ :mb-application-db-unreturned-connection-timeout 99})]
+ (is (= 99 (get (#'mdb.connection-pool-setup/application-db-connection-pool-props)
+ "unreturnedConnectionTimeout"))))))
+
(deftest reset-read-only-test
(testing "For Postgres app DBs, we should be executing `DISCARD ALL` when checking in a connection to reset state including read-only"
(when (= (app-db/db-type) :postgres)