How to Perform Surgical Edits on Large Text or JSON Columns Using db‑patch in Agent‑Native

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 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 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 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 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 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 <name> – Target table containing the column.
• --column <name> – Column to edit (typically TEXT or JSON type).
• --where "<clause>" – SQL predicate that uniquely identifies exactly one row (e.g., id = 42).
• --find "<text>" – Substring to locate within the column.
• --replace "<text>" – 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:

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:

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:

pnpm action db-patch \
  --table decks \
  --column data \
  --where "id = 7" \
  --find "<font color=\"red\">" \
  --replace "<font color=\"blue\">" \
  --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 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}