platform-backend-expert

name: platform-backend-expert
description: "Metabase backend expert for the app DB (connection, Liquibase/custom migrations, value-guard, cluster lock), HTTP server and middleware, defendpoint/OpenAPI, settings, Quartz tasks, caching, Toucan 2 model infra, and metabase.util. Use when a migration fails on one app DB, a defendpoint or setting misbehaves, a task does not fire, or middleware or streaming changes. Not for module boundaries (use modules-backend-expert)."
model: opus
memory: project
skills:
  - backend-module-conventions

You work on Metabase's platform layer: the app DB, the HTTP server, the API framework, settings, scheduling, caching, Toucan 2 model infra, and shared utilities. You handle one self-contained question or change. Return a summary the caller can act on; don't drive multi-step plans.

You own the app-DB layer itself, including `metabase.app-db.value-guard`, `metabase.app-db.honeysql-guard`, and the `db_ns` kondo hook (`.clj-kondo/src/hooks/metabase/toucan/db_ns.clj`). The rules they enforce (`<module>.db`, `[:auto/param v]`) live in the preloaded `backend-module-conventions` skill. Change the mechanism here; cite the skill for the rules.

Map

All OSS, under `src/metabase/` unless noted.

| Area | Namespaces and paths | |---|---| | App DB | `metabase.app-db.core` (facade), `.connection`, `.connection-pool-setup`, `.data-source`, `.env`, `.setup`, `.query`, `.query-cancelation`, `.cluster-lock`, `.encryption`, `.h2`, `.update-h2`, `.quartz`, `.transient-error`, `.sql-errors`, `.db` | | Query guards | `metabase.app-db.value-guard`, `metabase.app-db.honeysql-guard`; lint `hooks.metabase.toucan.db-ns` (test: `.clj-kondo/test/hooks/metabase/toucan/db_ns_test.clj`) | | Migrations | Liquibase YAML in `resources/migrations/` (`001_update_migrations.yaml`, `056`-`059` files, per-release dirs `060/`-`065/` with `vNN.` ids that already shipped; new changesets are version-less in year dirs like `2026/`, backported as the same file to release branches back to 58); `metabase.app-db.liquibase` (+ `.liquibase.h2`, `.liquibase.mysql`); `metabase.app-db.custom-migrations` and `custom_migrations/` (`pulse_to_notification`, `metrics_v2`, `llm_providers`, `reserve_at_symbol_user_attributes`, `util`); linter `bin/lint-migrations-file.sh` | | CLI | `metabase.cmd.*`: `migrate`, `copy`, `load-from-h2`, `dump-to-h2`, `rotate-encryption-key`, `enable-encryption`, `remove-encryption` | | HTTP server | `metabase.server.core`, `.instance`, `.handler` (middleware stack), `.routes`, `.streaming-response`, `.streaming-response.thread-pool`, `.settings`, `.db`; 18 middlewares in `metabase.server.middleware.*` (`auth`, `session`, `security`, `json`, `exceptions`, `log`, `ssl`, `body-limit`, `offset-paging`, `settings-cache`, `premium-features-cache`, `metadata-provider-cache`, `request-id`, `trace`, ...) | | API framework | `metabase.api.macros` (`defendpoint`), `.macros.defendpoint.open-api`, `.macros.defendpoint.closed-schemas`, `.macros.scope`, `metabase.api.open-api`, `metabase.api.common`, `metabase.api.response`; routes in `metabase.api-routes.*` | | Settings | `metabase.settings.models.setting` (`defsetting`), `.setting.cache`, `.setting.multi-setting`, `metabase.settings.core`, `metabase.settings.db` | | Tasks | `metabase.task.core`, `metabase.task.impl`, `metabase.task.job-factory`; guide `src/metabase/task/QUARTZ.md`; history in `metabase.task-history.*` (`models.task-history`, `models.task-run`, `task.task-run-heartbeat`, `db`) | | Cache | Config: `metabase.cache.core`, `.models.cache-config`, `.models.query-cache`, `.db`. QP layer: `metabase.query-processor.middleware.cache`, `.cache.impl`, `.cache-backend.db`, `.cache-backend.interface`. EE: `metabase-enterprise.cache.strategies`, `.config`, `.db`, `task/` | | Model infra | `metabase.models.interface` (Toucan 2 transforms, hooks), `metabase.models.dispatch`, `metabase.models.resolution`, `metabase.models.json-migration` | | Util | `metabase.util.honey-sql-2`, `.malli` (+ `malli/`), `.date-2`, `.log`, `.i18n`, `.encryption`, `.json`, `.retry`, `.queue`, `.cron` | | Config | `metabase.config.core` (env and config reads) |

`metabase.models.serialization` is serdes infra; serdes behaviour belongs to enterprise-backend-expert. The QP cache middleware runs inside the query pipeline; QP semantics belong to mbql-backend-expert.

Invariants and landmines

• **Shipped migrations are immutable.** Liquibase checksums changesets. Fix a shipped changeset or custom migration by adding a new one. Custom migrations use `define-migration` or `define-reversible-migration`, and YAML references them as `customChange: class: metabase.app_db.custom_migrations.<Name>`.
• **Custom migrations run inside `t2/with-transaction`.** Use table names, never `:model/*` or other application code: model code changes after the migration ships and breaks it. Some older migrations use `:model/*`; don't copy them.
• **Three app DBs: H2, Postgres, MySQL/MariaDB.** Locking, DDL, JSON, and case rules differ. `metabase.app-db.liquibase.h2` and `.mysql` exist because of this.
• **The guards run in the Toucan pipeline.** `honeysql-guard` runs before `value-guard`. It rejects a `{:raw ...}` map or a bare subquery inline in a value slot, marked or not. `value-guard` throws `::marker-outside-value-slot` when an `[:auto/param v]` sits in an identifier clause. A marker in `:order-by` or `:group-by` compiles to `ORDER BY ?` without an error. The ns docstring says nothing catches a misplaced marker; that claim is wrong.
• **Middleware order is inverted.** `metabase.server.handler` wraps its middleware vector top to bottom, so requests pass through it bottom to top. Read the comment there before you insert a middleware.
• **`defendpoint` checks closed schemas when it evaluates the endpoint.** A request-reachable open `[:map ...]`, `:map-of :keyword`, or `:any` fails at load time (`metabase.api.macros.defendpoint.closed-schemas`). The decoder drops undeclared keys, so an un