> Raw Markdown twin (generated at build time from the source Markdown). Rendered page: https://docs.gatellm.io/en/console/config-batch · Doc index: https://docs.gatellm.io/en/llms.txt


# Batch configuration (models and load balancers)

Batch configuration collects changes to multiple **models** and **load balancers** into one batch: first stage (no DB writes), preview this batch's impact on the namespace (freed/taken/conflicts), then after confirmation **commit atomically** — either all take effect, or none is written. Suitable for one-shot migration or renaming a set of mutually-referencing entities, avoiding the intermediate inconsistent states caused by saving one by one.

Entry: Console → **Tools** → **Batch configuration** tab (admin only).

> v1 scope: only **models** and **load balancers** participate in batching (they are entities sharing a globally unique namespace). Other entities such as upstreams and access keys still use their own single-item edit pages.

## Workflow

```
Stage operations (create/update/rename/delete, multiple allowed)
    → Preview (POST /config/batch/preview, namespace impact + full conflict set, no DB writes)
    → Confirm → Commit (POST /config/batch, atomic commit in one transaction)
```

1. **Stage operations**: on the batch configuration page, create, edit, rename, or delete models / load balancers. Each step only **stages** into the pending list and does not immediately write to the DB — the page lists all currently staged operations.
2. **Preview impact**: before committing, review the preview — which names this batch will **free**, which names it will **take**, and whether there are any **conflicts** with the existing configuration. The preview is a read-only dry run and writes no data.
3. **Atomic commit**: commit after confirming there are no conflicts. The whole batch is written in **one transaction**; if any operation conflicts or fails, the **whole batch rolls back**, with no half-written state.

> **How renames arise**: when you edit an existing entity and change its name, staging automatically recognizes it as a **rename** operation (old name freed, new name taken); you don't need to select "Rename" separately.

## What the preview shows

The preview gives this batch's namespace impact:

- **Freed**: names this batch will vacate (e.g. old names given up by deletion or rename).
- **Taken**: names this batch will occupy (e.g. new names from create or rename).
- **Conflicts**: naming conflicts with the existing configuration. The preview returns the **full conflict set** (not just the first one), so you can see all problems at once.

With no conflicts, it shows "This batch can be committed"; with conflicts, resolve them before committing.

## Console API

| Endpoint | Description |
|------|------|
| `POST /console/api/config/batch/preview` | Dry-runs a batch of operations and returns the namespace impact and conflict set; no DB writes, no lock |
| `POST /console/api/config/batch` | Atomically commits a batch of operations (one transaction; any conflict rolls back the whole batch) |

Each operation is an object with a `kind` tag (`create` / `update` / `rename` / `delete`), `entity_type` is `models` / `load_balancers`, and `entity` is the same form payload as a single create/edit. After a successful commit, a config reload is triggered and broadcast across instances.

## FAQ

**Q: What if I staged halfway and don't want to commit?**
Staged operations only exist in the current page's pending list and are not written to the DB; leaving the page or clearing the list abandons them, without affecting live configuration.

**Q: Getting conflicts when committing?**
The preview stage already lists the full conflict set (names taken, etc.). Rename or adjust as prompted, then commit. Atomic commit guarantees there is no half-written state on conflict.

**Q: Can I batch-edit access keys / upstreams?**
In v1, only models and load balancers participate in batching. Other entities are operated one at a time on their own management pages.

**Next**: [Upstream and model fields](/en/reference/upstreams-models-fields.md) for model fields; [Load-balancing fields](/en/reference/load-balancing-fields.md) for LB fields; [Console login and roles](/en/console/login-and-roles.md) for page permissions.