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 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.cljindex 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` filebecause 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 usedbelow (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/pooledDataSourcedata-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.mdindex 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 browAlso 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 forSee [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.cljindex 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)