# How to Perform Surgical Edits on Large Text or JSON Columns Using db‑patch in Agent‑Native > Efficiently edit large text or JSON columns in Agent-Native with db-patch. Learn to use this CLI action for compact diffs and save tokens on massive blobs. - Repository: [Builder.io/agent-native](https://github.com/BuilderIO/agent-native) - Tags: how-to-guide - Published: 2026-07-02 --- **Use the `db‑patch` CLI action to transmit compact `{find, replace}` diffs instead of full column values, enabling efficient token‑saving edits of massive Markdown, HTML, or JSON blobs stored in Agent‑Native.** Agent‑Native provides a purpose‑built `db‑patch` tool that solves the bandwidth problem of updating large text fields. When an AI agent fixes a typo in a 50 KB Markdown document or tweaks a single key in a dashboard JSON configuration, transmitting the entire column value wastes tokens and slows inference. Instead, `db‑patch` sends surgical diffs that the server applies via SQL `REPLACE` operations, keeping payloads minimal and workflows fast. ## Why Surgical Edits Matter for Large Columns Large content fields—such as slide HTML, documentation Markdown, or dashboard JSON—often reach tens of kilobytes. A conventional `db-exec UPDATE` would serialize the entire new value across the network, consuming unnecessary LLM context window space. According to the internal documentation in [`templates/mail/.agents/skills/storing-data/SKILL.md`](https://github.com/BuilderIO/agent-native/blob/main/templates/mail/.agents/skills/storing-data/SKILL.md) at lines 75‑89, `db‑patch` is the recommended approach when you are changing a small slice of a large column because it transmits only the delta. ## How db‑patch Works Under the Hood When the Agent‑Native server initializes, the chat plugin registers `db‑patch` alongside other database utilities in [`packages/core/src/server/agent-chat-plugin.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/server/agent-chat-plugin.ts) at line 1447. The tool constructs a SQL `UPDATE` statement that uses the native `REPLACE(column, find, replace)` function to patch the target cell in‑place. ### Authentication and Scoping Guards Before executing any mutation, `db‑patch` validates two critical constraints defined in [`packages/core/src/scripts/db/scoping.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/scripts/db/scoping.ts) at line 51: - **Authentication**: The caller must be an authenticated user. - **Row Uniqueness**: The `--where` clause must resolve to exactly one primary‑key row, preventing accidental mass updates. These guards ensure that patches stay scoped to the application database—specifically `settings`, `application_state`, and template tables—and cannot touch external data sources, as enforced by the shared rules in [`packages/core/src/server/prompts/shared-rules.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/server/prompts/shared-rules.ts) at line 64. ### Automatic UI Refresh Because mutations occur through the internal application database layer, the Agent‑Native framework automatically broadcasts refresh signals to connected clients upon completion. As noted in [`packages/core/src/server/prompts/framework-core.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/server/prompts/framework-core.ts) at line 54, this eliminates the need for explicit `refresh-screen` calls after a successful patch. ## Command Syntax and Supported Flags Invoke `db‑patch` via the Agent‑Native CLI using `pnpm action db‑patch` followed by these flags: - **`--table `** – Target table containing the column. - **`--column `** – Column to edit (typically `TEXT` or `JSON` type). - **`--where ""`** – SQL predicate that uniquely identifies exactly one row (e.g., `id = 42`). - **`--find ""`** – Substring to locate within the column. - **`--replace ""`** – Replacement string for the first match only. - **`--edits '[{find,replace},...]'`** – JSON array for performing multiple disjoint replacements in a single call. - **`--all`** – Replace every occurrence of `--find` instead of just the first. ## Practical Usage Examples ### Single Replacement in Markdown Content Fix a typo in a large document without transmitting the full file: ```bash pnpm action db-patch \ --table documents \ --column content \ --where "id = 123" \ --find "typo" \ --replace "correction" ``` ### Batch Edits on JSON Configuration Update multiple keys inside a dashboard JSON blob using the `--edits` flag: ```bash pnpm action db-patch \ --table dashboards \ --column config \ --where "id = 42" \ --edits '[{"find":"\"title\":\"Old\"","replace":"\"title\":\"New\""}, {"find":"\"theme\":\"light\"","replace":"\"theme\":\"dark\""}]' ``` ### Global Replacements in HTML Slides Change every occurrence of a font color across all slides in a deck by adding the `--all` flag: ```bash pnpm action db-patch \ --table decks \ --column data \ --where "id = 7" \ --find "" \ --replace "" \ --all ``` Each command emits a compact diff that the server applies atomically, leaving surrounding content untouched. ## Summary - **Use `db‑patch`** when you need to perform surgical edits on large text or JSON columns in Agent‑Native. - **Token efficiency**: The tool sends only `{find, replace}` pairs rather than full column values, preserving LLM context window. - **Safety**: Built‑in scoping in [`packages/core/src/scripts/db/scoping.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/scripts/db/scoping.ts) restricts edits to one authenticated row at a time. - **Auto‑refresh**: Successful patches automatically trigger UI updates without manual refresh calls. - **Batch support**: Use the `--edits` JSON array flag for multiple surgical replacements in a single transaction. ## Frequently Asked Questions ### Can db‑patch update multiple rows at once? No. The tool enforces a strict scoping rule requiring the `--where` clause to resolve to exactly one primary‑key row. This guardrail, implemented in [`packages/core/src/scripts/db/scoping.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/scripts/db/scoping.ts), prevents accidental mass updates across the application database. ### What happens if the find string doesn't exist in the column? The SQL `REPLACE` function returns the original column value unchanged when the search substring is absent. The operation succeeds but makes no modifications, and the UI refresh still triggers to confirm the state. ### Is db‑patch limited to text columns, or does it work with binary data? `db‑patch` is designed for large text and JSON columns. It uses SQL string replacement functions that operate on character data, making it unsuitable for binary blobs or non‑textual column types. ### How does db‑patch handle JSON escaping in the `--edits` array? When using `--edits`, you must provide valid JSON with escaped quotes. The shell command parses the array before transmission, and the server applies each `find`/`replace` pair sequentially using SQL `REPLACE` logic, preserving the JSON structure as long as your patterns maintain valid syntax.