Skip to content
Skills Library
Programming · Building & coding

backend-module-conventions

/backend-module-conventions

Where Metabase backend code goes and how it reaches the app DB. Covers module layout, the `<module>.db` rule, `[:auto/param]` value binding, module config, and pre-handoff checks. Use when adding or moving backend namespaces, writing app-DB queries, or touching module boundaries. Preloaded by every `*-backend-expert` agent.

Repository
metabase ↗
Licence
AGPL-3.0
Last repository change
25.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

AGPL-3.0, copyleft: przeróbki udostępniane innym muszą mieć tę samą licencję.

What it does and when to use it

Where Metabase backend code goes and how it reaches the app DB. Covers module layout, the `<module>.db` rule, `[:auto/param]` value binding, module config, and pre-handoff checks. Use when adding or moving backend namespaces, writing app-DB queries, or touching module boundaries. Preloaded by every `*-backend-expert` agent.

Original author description

Where Metabase backend code goes and how it reaches the app DB. Covers module layout, the `<module>.db` rule, `[:auto/param]` value binding, module config, and pre-handoff checks. Use when adding or moving backend namespaces, writing app-DB queries, or touching module boundaries. Preloaded by every `*-backend-expert` agent.

How it works

  1. Split a module into standard namespaces
  2. Keep app-DB access in <module>.db
  3. Add app-DB migrations
  4. Cross module boundaries through :api
  5. Verify before handing work back
Original SKILL.md headings · 88 lines, 866 words
SKILL.md preview
---
name: backend-module-conventions
description: Where Metabase backend code goes and how it reaches the app DB. Covers module layout, the `<module>.db` rule, `[:auto/param]` value binding, module config, and pre-handoff checks. Use when adding or moving backend namespaces, writing app-DB queries, or touching module boundaries. Preloaded by every `*-backend-expert` agent.
---

# Backend module conventions

This skill decides where a line of backend code lives and how it reaches the app DB. Project `CLAUDE.md`
covers the module config keys, nested modules, test commands, and ratchets. When the two disagree, the
source tree wins. Read the linter or test that enforces a rule before you trust any prose about it,
including this file.

## Split a module into standard namespaces

A module is `metabase.<module>` (OSS, `src/`) or `metabase-enterprise.<module>` (EE,
`enterprise/backend/src/`). Most modules split into these namespaces:

| Namespace | Holds |
|---|---|
| `<module>.core` | The public API. Other modules call only this (plus anything else listed in the module's `:api`). Often a `potemkin/import-vars` facade. |
| `<module>.db` | Every app-DB query the module makes. See the next section. |
| `<module>.models.*` | Toucan 2 model definitions: `methodical/defmethod t2/table-name`, hooks, transforms. |
| `<module>.settings` | `defsetting`s. |
| `<module>.init` | Requires the namespaces that register things as a side effect (settings, tasks, event handlers). `metabase.core.init` or `metabase-enterprise.core.init` requires it. |
| `<module>.api`, or the nested `<module>.rest` module (`:ns-prefix "metabase.<module>-rest"`, dir `<module>_rest/`) | HTTP endpoints. Domain logic stays in the base module. The `.rest` child calls the parent's `.core`. |
| `enterprise/<module>` | The EE companion of an OSS module. It nests under the OSS module, which exports it automatically. |

If a setting, task, or event handler never takes effect, look for a missing link in the `.init` chain.

## Keep app-DB access in `<module>.db`

Call Toucan 2 query functions (`t2/select*`, `t2/insert!`, `t2/update!`, `t2/delete!`, `t2/count`,
`t2/exists?`, `t2/query`, ...) and the `metabase.app-db.core` wrappers (`mdb/query`,
`mdb/update-or-insert!`, ...) only from `metabase[-enterprise].<module>.db`. Driver code uses
`metabase.driver.<driver>.db`. Every other namespace calls functions from its own module's `db`.
The kondo hook `hooks.metabase.toucan.db-ns` reports violations as `:metabase/t2-query-namespace`.
Test files are exempt.

Write `db` functions in the style of `src/metabase/settings/db.clj`:

- Make each function a thin `mu/defn` that wraps one query and adds no logic. Give it a docstring that says what it returns.
- Name functions after the domain question (`setting-value`, `delete-setting!`), not after SQL.
- Keep branching, permission checks, and data shaping in the caller. A `db` function that grows an `if` belongs somewhere else.
- Get cross-module data through the other module's `.core`, not its `db`. A few modules list their `db` in `:api` as legacy exceptions. Don't add more.

### Bind values with `[:auto/param v]`

`metabase.app-db.value-guard` binds a value written as `[:auto/param v]` as a SQL parameter. The
`:metabase/unsafe-app-db-query` lint is off globally. `.clj-kondo/config.edn` turns it on per namespace
under `:config-in-ns`, one converted `db.clj` at a time. Follow these rules in every `db.clj`, whether or
not the lint covers it yet:

1. Mark a value that comes from a variable when it sits in a **value slot**. Value slots are the right-hand side of `:=`, `:in`, `:like`, ..., and kv-arg values used as filters.
2. Never mark a literal. A literal cannot carry a request value.
3. Never mark a value in an **identifier slot** (`:select`, `:from`, joins, aliases, and similar). `value-guard` throws `::marker-outside-value-slot` at compile time. In `:order-by` and `:group-by` a marker compiles to `ORDER BY ?`, which is useless but does not throw. Don't write one there either.
4. Leave a possibly-empty collection unmarked. Toucan rewrites `[:in col []]` to `false` before the marker step.
5. Leave values that `t2/update!` *writes* unmarked. Model hooks such as encryption must still see them.
6. Keep kv-arg style (`:engine engine`) for a column with a Toucan type transform. If you move a keyword value into a raw `{:where ...}` map, the transform is skipped. HoneySQL then formats the keyword as an identifier, and the query returns wrong rows without failing.

The docstring of `metabase.app-db.value-guard` explains what the guard refuses without any marker.

## Add app-DB migrations

Follow the `app-db-migrations` skill (`.claude/skills/app-db-migrations/SKILL.md`): changesets are version-less, live
in year directories like `resources/migrations/2026/` (`./bin/mage new-migration <name>`), and are backported by
cherry-picking the same file to each release branch. `./bin/lint-migrations-file.sh` enforces the rules. The versioned
layout (`0NN/` directories, `vNN.` ids) only holds changesets that already shipped.

The whole `metabase.app-db.*` module, custom migrations included, is exempt from the `<module>.db` rule (the
`app-db-namespaces` group in `.clj-kondo/config.edn`).

## Cross module boundaries through `:api`

- `.clj-kondo/config/modules/config.edn` declares `:api`, `:uses`, `:model-exports`, and `:model-imports` per module. Run `./bin/mage fix-modules-config` after you add or remove a namespace, a cross-module require, or a cross-module `:model/X` reference. If nothing drifted, it does nothing.
- `./bin/mage modules-tree` prints the hierarchy. The `dev.deps-graph` and `dev.module-score` namespaces show who uses a module externally.
- If a module needs something outside another module's `:api`, choose the first fix that works:
  1. Call something that is already public.
  2. Add the var to that module's `.core`.
  3. Invert the dependency with an event (`metabase.events`).

  Don't add a `:clj-kondo/ignore`.
- If you change a suppression or a module escape hatch, run `./bin/mage kondo-ratchets`.

## Verify before handing work back

1. Load each changed namespace in the REPL (`clojure-eval` skill). If no REPL is available, run `./bin/test-agent :only '[the.ns-test]'`.
2. Run the narrowest tests that cover the change. Use `./bin/test-agent :module <module>` to check blast radius.
3. Run `./bin/mage kondo-updated` on the changed files.
4. If a boundary moved, run `./bin/mage fix-modules-config`.

Report which of these steps ran, and what each one showed.

Versions

The database has no other skills named backend-module-conventions.

Database snapshot: 13.11.2026 · package version 4514509809f4 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90backend-module-standards
    Enforce this repository's TypeScript backend module architecture standards. Use whenever creating, modifying, refactoring, or reviewing backend code under `server/`, including routes, services, modules, repositories, shared backend code, and backend tests. Do not apply these…
  • 90js-module-structure
    Directory, file role and named-export conventions that decide where code goes in non-backend JS/TS projects. Use when creating a module, adding api / store / hooks / utils / pages to a frontend app, adding types, constants, styles or tests to an existing module, or reorganizing…
  • 100name-module-cycle
    Suggest a space-themed name for a cyclic cluster of backend modules when metabase.core.module-cycles-test reports a cluster without a name, usually after a split. Use when someone needs to name a module cycle or add a line to .clj-kondo/config/modules/cycle-clusters.edn.
  • 100nestjs-module-generator
    Generate nestjs module generator operations. Auto-activating skill for Backend Development. Triggers on: nestjs module generator, nestjs module generator Part of the Backend Development skill category. Use when working with nestjs module generator functionality. Trigger with…
  • 100metabase-full-app-to-modular-embedding-upgrade
    Migrates a project from Metabase Full App / Interactive (iframe-based) embedding to Modular (web-component-based) embedding. Use when the user wants to replace Metabase iframes with Modular embedding web components.
  • 100app-db-migrations
    Add, test, run and roll back application-database (Liquibase) migrations. Use when adding a changeset, changing a table or column in the Metabase app DB, writing a custom (Clojure) migration, or rolling migrations back in development.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.