diff --git a/.serena/memories/backend/subtleties.md b/.serena/memories/backend/subtleties.md index 9a655aaa95..4fdfbf3f81 100644 --- a/.serena/memories/backend/subtleties.md +++ b/.serena/memories/backend/subtleties.md @@ -51,6 +51,7 @@ - `app.config/config` and `flags` are dynamic `defonce` vars populated from `PENPOT_*` env vars through the shared schema string transformer. Tests and tooling can bind them. - Duration config values are parsed as ISO-8601 with the `PT` prefix, so a day is written in hours (`:jobs-retention` and `:jobs-user-ttl` default to a week, and an operator writes `168h`): `7d` does not parse, and the value fails validation at boot instead of being silently ignored. +- `app.main` wires `PENPOT_DATABASE_*` into `::db/pool`, and `app.db/create-datasource-config` forwards pgjdbc's own knobs as `dataSourceProperties`, which `Properties.getProperty` silently drops unless the value is a String (hence the `str`). A query parameter of the same name in `PENPOT_DATABASE_URI` (for example `?prepareThreshold=0`) wins over the property: pgjdbc ignores the Properties value when the URL carries it, so the URI is the place to look when a variable seems to do nothing. The prepared statement cache is three optional `PENPOT_DATABASE_PREPARED_STATEMENT_CACHE_*` keys: the threshold is the executions before a statement is server-prepared and accepts `-1` or non-negatives (`{:min -1}`; the driver clamps any other negative to `-1`, so rejecting it only turns a typo into a boot error), its `0` stops server-side prepared statements while the driver's client-side cache of parsed queries stays in use, `..._QUERIES` and `..._SIZE` reject negatives and `0` in either disables that cache, and the size is bytes rounded up to the whole MiB the driver accepts. Do not describe the threshold `0` as disabling the cache: it only stops the server-side prepares. - `parse-flags` automatically adds `:disable-secure-session-cookies` when `public-uri` is plain HTTP and not localhost. This changes cookie defaults without an explicit env flag. - The backend sets Clojure `*assert*` globally from the `:backend-asserts` feature flag. Assertion-dependent checks can therefore differ by runtime flags. - Request body parsing is mostly POST-oriented and supports Transit JSON plus plain JSON. Plain JSON request keys are kebab-decoded before being merged into `:params`. A body the parser cannot read is a client error, classified at the parse site and never by exception class (`clojure.data.json` signals its syntax errors with a bare `java.lang.Exception`): 400 `:validation`/`:malformed-json`, one `warn` line (`malformed request body`) carrying path, peer address and content-type instead of a stack trace, and `penpot_http_malformed_requests_total`. `RequestTooBigException` keeps its 413. diff --git a/backend/src/app/config.clj b/backend/src/app/config.clj index a5ab682bb4..206336ca97 100644 --- a/backend/src/app/config.clj +++ b/backend/src/app/config.clj @@ -241,6 +241,12 @@ [:database-readonly {:optional true} ::sm/boolean] [:database-min-pool-size {:optional true} ::sm/int] [:database-max-pool-size {:optional true} ::sm/int] + ;; pgjdbc prepared statement cache (see app.db). Size is in bytes and is + ;; converted to the whole MiB the driver accepts. Absent keys mean the + ;; driver defaults; see docs/technical-guide/configuration.md. + [:database-prepared-statement-cache-threshold {:optional true} [::sm/int {:min -1}]] + [:database-prepared-statement-cache-queries {:optional true} [::sm/int {:min 0}]] + [:database-prepared-statement-cache-size {:optional true} [::sm/int {:min 0}]] [:quotes-teams-per-profile {:optional true} ::sm/int] [:quotes-access-tokens-per-profile {:optional true} ::sm/int] diff --git a/backend/src/app/db.clj b/backend/src/app/db.clj index bfce3b2274..8bdeae67a4 100644 --- a/backend/src/app/db.clj +++ b/backend/src/app/db.clj @@ -57,7 +57,9 @@ (def ^:private schema:pool-options [:map {:title "pool-options"} - [::connect-timeout {:optional true} ::sm/int] + [::connection-timeout {:optional true} ::sm/int] + [::idle-timeout {:optional true} ::sm/int] + [::max-lifetime {:optional true} ::sm/int] [::max-size {:optional true} ::sm/int] [::min-size {:optional true} ::sm/int] [::name {:optional true} :keyword] @@ -66,6 +68,17 @@ [::username {:optional true} :string] [::validation-timeout {:optional true} ::sm/int] [::read-only {:optional true} ::sm/boolean] + ;; pgjdbc prepared statement cache. Absent keys mean the driver + ;; defaults; the size is in bytes and is converted to whole MiB for + ;; the driver (see create-datasource-config). The threshold is the + ;; executions before a statement is server-prepared: 0 stops + ;; server-side prepared statements (the cache of parsed queries stays + ;; in use) and -1 prepares from the first execution. Any other + ;; negative is a typo the driver would clamp to -1, so the schema + ;; rejects it. + [::prepared-statement-cache-threshold {:optional true} [::sm/int {:min -1}]] + [::prepared-statement-cache-queries {:optional true} [::sm/int {:min 0}]] + [::prepared-statement-cache-size {:optional true} [::sm/int {:min 0}]] [::mtx/metrics ::mtx/metrics]]) (def defaults @@ -94,7 +107,10 @@ :credentials (and (contains? cfg ::username) (contains? cfg ::password)) :min-size (::min-size cfg) - :max-size (::max-size cfg)) + :max-size (::max-size cfg) + :prepared-statement-cache-threshold (::prepared-statement-cache-threshold cfg) + :prepared-statement-cache-queries (::prepared-statement-cache-queries cfg) + :prepared-statement-cache-size (::prepared-statement-cache-size cfg)) (create-pool cfg)))) (defmethod ig/halt-key! ::pool @@ -113,6 +129,17 @@ ;; pairwise, when both are partitioned with the same bounds "SET enable_partitionwise_join = on;")) +;; pgjdbc reads dataSourceProperties through Properties.getProperty, which +;; drops non-String values silently, so everything is passed as a string. +;; preparedStatementCacheSizeMiB only accepts a whole-MiB integer: the +;; configured size (bytes) is converted up, so any positive value keeps the +;; cache enabled and 0 disables the cache. A query parameter of the same name +;; in the URI wins over these properties: pgjdbc ignores the Properties value +;; when the URL carries it. +(defn- bytes->mib-ceil + [bytes] + (Math/ceilDiv (long bytes) (* 1024 1024))) + (defn- create-datasource-config [{:keys [::uri] :as cfg}] @@ -132,6 +159,13 @@ (.setConnectionInitSql initsql) (.setInitializationFailTimeout -1)) + (some->> (::prepared-statement-cache-threshold cfg) (str) + (.addDataSourceProperty config "prepareThreshold")) + (some->> (::prepared-statement-cache-queries cfg) (str) + (.addDataSourceProperty config "preparedStatementCacheQueries")) + (some->> (::prepared-statement-cache-size cfg) (bytes->mib-ceil) (str) + (.addDataSourceProperty config "preparedStatementCacheSizeMiB")) + (->> (mtx/get-registry (::mtx/metrics cfg)) (PrometheusMetricsTrackerFactory.) (.setMetricsTrackerFactory config)) diff --git a/backend/src/app/main.clj b/backend/src/app/main.clj index 71ddafd9bf..79033f9442 100644 --- a/backend/src/app/main.clj +++ b/backend/src/app/main.clj @@ -425,6 +425,9 @@ ::db/read-only (cf/get :database-readonly false) ::db/min-size (cf/get :database-min-pool-size) ::db/max-size (cf/get :database-max-pool-size) + ::db/prepared-statement-cache-threshold (cf/get :database-prepared-statement-cache-threshold) + ::db/prepared-statement-cache-queries (cf/get :database-prepared-statement-cache-queries) + ::db/prepared-statement-cache-size (cf/get :database-prepared-statement-cache-size) ::mtx/metrics (ig/ref ::mtx/metrics)} ;; Default netty IO pool (shared between several services) diff --git a/backend/test/backend_tests/config_test.clj b/backend/test/backend_tests/config_test.clj index fa168708ef..5e0e2418b8 100644 --- a/backend/test/backend_tests/config_test.clj +++ b/backend/test/backend_tests/config_test.clj @@ -76,6 +76,23 @@ :worker-default-parallelism 4)] (t/is (= 4 (cf/get :worker-default-parallelism 1)))))) +(t/deftest prepared-statement-cache-keys + (t/testing "negative sizes are rejected; the threshold takes -1 or non-negatives" + (t/is (not (cf/validate-config (assoc cf/config :database-prepared-statement-cache-queries -1)))) + (t/is (not (cf/validate-config (assoc cf/config :database-prepared-statement-cache-size -1)))) + (t/is (not (cf/validate-config (assoc cf/config :database-prepared-statement-cache-threshold -2)))) + (t/is (cf/validate-config (assoc cf/config :database-prepared-statement-cache-threshold -1)))) + (t/testing "a -1 threshold survives the environment decoding and validation" + (let [cfg (merge cf/config + (cf/decode-config {:database-prepared-statement-cache-threshold "-1"}))] + (t/is (= -1 (:database-prepared-statement-cache-threshold cfg))) + (t/is (cf/validate-config cfg)))) + (t/testing "a decoded -2 threshold fails validation" + (let [cfg (merge cf/config + (cf/decode-config {:database-prepared-statement-cache-threshold "-2"}))] + (t/is (= -2 (:database-prepared-statement-cache-threshold cfg))) + (t/is (not (cf/validate-config cfg)))))) + (t/deftest jobs-user-ttl (t/testing "the env value is decoded as a duration" (let [decoded (cf/decode-config {:jobs-user-ttl "72h"})] diff --git a/backend/test/backend_tests/db_test.clj b/backend/test/backend_tests/db_test.clj index b0f20cb256..71de5b7b24 100644 --- a/backend/test/backend_tests/db_test.clj +++ b/backend/test/backend_tests/db_test.clj @@ -36,6 +36,113 @@ (do (Thread/sleep 10) (recur (dec attempt))))))) +(t/deftest pool-passes-prepared-statement-cache-properties + ;; The driver reads dataSourceProperties through Properties.getProperty, + ;; which keeps only String values, so the wiring must set them as strings. + ;; Comparing the literals alone cannot catch a property the driver ignores, + ;; so the threshold cases also read it back from a real connection. + (let [metrics (ig/init-key :app.metrics/metrics {:default {}}) + init-pool (fn [opts] + (ig/init-key :app.db/pool + (merge {:app.db/uri (java.net.URI. "postgresql://localhost/test") + :app.metrics/metrics metrics + :app.db/name :test-prepared-statement-cache} + opts))) + with-connection (fn [opts f] + (let [ds (init-pool (merge {:app.db/uri (:database-uri th/config) + :app.db/username (:database-username th/config) + :app.db/password (:database-password th/config)} + opts))] + (try + (with-open [conn (.getConnection ^HikariDataSource ds)] + (f conn)) + (finally + (.close ^HikariDataSource ds))))) + prepare-threshold (fn [conn] + (.getPrepareThreshold + ^org.postgresql.PGConnection + (.unwrap conn org.postgresql.PGConnection)))] + (t/testing "absent keys stay absent" + (let [ds (init-pool {})] + (t/is (empty? (.getDataSourceProperties ^HikariDataSource ds))) + (.close ^HikariDataSource ds))) + (t/testing "the driver defaults apply when no option is set" + (with-connection {} (fn [conn] (t/is (= 5 (prepare-threshold conn)))))) + (t/testing "configured keys reach the driver as strings" + (let [ds (init-pool {:app.db/prepared-statement-cache-threshold 1 + :app.db/prepared-statement-cache-queries 512 + :app.db/prepared-statement-cache-size 10485760}) + props (.getDataSourceProperties ^HikariDataSource ds)] + (t/is (= "1" (.getProperty props "prepareThreshold"))) + (t/is (= "512" (.getProperty props "preparedStatementCacheQueries"))) + (t/is (= "10" (.getProperty props "preparedStatementCacheSizeMiB"))) + (.close ^HikariDataSource ds))) + (t/testing "a configured threshold reaches the driver" + (with-connection {:app.db/prepared-statement-cache-threshold 1} + (fn [conn] (t/is (= 1 (prepare-threshold conn))))) + (with-connection {:app.db/prepared-statement-cache-threshold 0} + (fn [conn] (t/is (= 0 (prepare-threshold conn)))))) + (t/testing "a -1 threshold reaches the driver (forceBinary)" + (let [ds (init-pool {:app.db/prepared-statement-cache-threshold -1})] + (t/is (= "-1" (.getProperty (.getDataSourceProperties ^HikariDataSource ds) + "prepareThreshold"))) + (.close ^HikariDataSource ds))) + (t/testing "a zero threshold reaches the driver (server-side statements off)" + (let [ds (init-pool {:app.db/prepared-statement-cache-threshold 0})] + (t/is (= "0" (.getProperty (.getDataSourceProperties ^HikariDataSource ds) + "prepareThreshold"))) + (.close ^HikariDataSource ds))) + (t/testing "a positive sub-MiB size rounds up so the cache stays enabled" + (let [ds (init-pool {:app.db/prepared-statement-cache-size 1})] + (t/is (= "1" (.getProperty (.getDataSourceProperties ^HikariDataSource ds) + "preparedStatementCacheSizeMiB"))) + (.close ^HikariDataSource ds))) + (t/testing "the MiB ceiling rounds a byte over the boundary up" + (let [ds (init-pool {:app.db/prepared-statement-cache-size 1048577})] + (t/is (= "2" (.getProperty (.getDataSourceProperties ^HikariDataSource ds) + "preparedStatementCacheSizeMiB"))) + (.close ^HikariDataSource ds))) + (t/testing "the cache limits hold a closed statement in the server" + ;; A closed statement stays prepared in the server only while the + ;; driver's cache holds it, so counting it in pg_prepared_statements is + ;; what tells an accepted property from an effective one. + (let [cached? (fn [opts] + (with-connection + (merge {:app.db/prepared-statement-cache-threshold 1} opts) + (fn [conn] + (dotimes [_ 2] + (with-open [stmt (.prepareStatement ^Connection conn "SELECT ?::int AS cache_probe")] + (.setInt stmt 1 1) + (with-open [rs (.executeQuery stmt)] (.next rs)))) + (-> (db/exec-one! conn ["SELECT count(*) AS n FROM pg_prepared_statements + WHERE statement LIKE '%AS cache_probe'"]) + :n + pos?))))] + (t/testing "a positive sub-MiB size keeps the cache enabled" + (t/is (cached? {:app.db/prepared-statement-cache-size 1}))) + (t/testing "zero size disables the cache" + (t/is (not (cached? {:app.db/prepared-statement-cache-size 0})))) + (t/testing "zero queries disables the cache" + (t/is (not (cached? {:app.db/prepared-statement-cache-queries 0})))))))) + +(t/deftest pool-rejects-a-non-minus-one-negative-threshold + ;; The pool boundary mirrors app.config: -1 prepares from the first + ;; execution, 0 stops server-side prepared statements, and any other + ;; negative is a typo the driver would silently clamp to -1. + (let [options {:app.db/uri (:database-uri th/config) + :app.db/username (:database-username th/config) + :app.db/password (:database-password th/config) + :app.metrics/metrics (ig/init-key :app.metrics/metrics {:default {}})}] + (t/testing "a -2 threshold fails the pool schema" + (t/is (thrown? clojure.lang.ExceptionInfo + (ig/assert-key :app.db/pool + (assoc options :app.db/prepared-statement-cache-threshold -2))))) + (t/testing "-1 and 0 pass the pool schema" + (t/is (nil? (ig/assert-key :app.db/pool + (assoc options :app.db/prepared-statement-cache-threshold -1)))) + (t/is (nil? (ig/assert-key :app.db/pool + (assoc options :app.db/prepared-statement-cache-threshold 0))))))) + (t/deftest pool-requires-metrics ;; Metrics is required by the pool schema: a pool wired without it ;; fails at the boundary (AssertionError when asserts are enabled) or diff --git a/docs/technical-guide/configuration.md b/docs/technical-guide/configuration.md index 4cda6efef4..17e0914e15 100644 --- a/docs/technical-guide/configuration.md +++ b/docs/technical-guide/configuration.md @@ -780,6 +780,33 @@ If the PostgreSQL server is shared with other applications, make sure `PENPOT_DATABASE_MAX_POOL_SIZE` plus the connections used by everything else stays below the server's `max_connections` (100 by default). +#### Prepared statement cache + +__Since version 2.20.0__ + +The driver keeps two things per connection: a cache of parsed queries and, once a query +runs enough times, a statement prepared in the server whose plan the server can reuse. +Both are on by default; you only need these settings to tune them or to turn them off: + +```bash +# Backend +PENPOT_DATABASE_PREPARED_STATEMENT_CACHE_THRESHOLD: 5 +PENPOT_DATABASE_PREPARED_STATEMENT_CACHE_QUERIES: 256 +PENPOT_DATABASE_PREPARED_STATEMENT_CACHE_SIZE: 5242880 +``` + +The values above are the driver defaults. `PENPOT_DATABASE_PREPARED_STATEMENT_CACHE_THRESHOLD` +is how many times a query runs on a connection before the driver prepares it server-side: +`-1` prepares it from the first execution and forces binary transfer, and `0` stops the +driver from preparing statements in the server. The cache of parsed queries stays in use +with the threshold at `0`: the connection caches up to +`PENPOT_DATABASE_PREPARED_STATEMENT_CACHE_QUERIES` queries, using at most +`PENPOT_DATABASE_PREPARED_STATEMENT_CACHE_SIZE` bytes per connection (the size is rounded +up to whole MiB for the driver), and setting either of those two to `0` disables the +cache. With 60 connections, the ceiling is 60 × the size. Leave a variable unset and the +driver default applies. A parameter of the same name in `PENPOT_DATABASE_URI`, such as +`?prepareThreshold=0`, takes precedence over these variables. + ### Storage Storage refers to storing the user uploaded different objects in Penpot (assets, file data,...).