mongodb-transactions-consistency

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MongoDB Transactions and Consistency

MongoDB事务与一致性

Transaction and consistency guidance for MongoDB, maintained by MongoDB. Contains 20 rules across 5 categories, prioritized by correctness risk. This skill is intentionally non-overlapping with schema and query/index skills: it focuses on atomicity, isolation, durability, retries, and consistency semantics.

这是由MongoDB维护的MongoDB事务与一致性指南，包含5个类别下的20条规则，按正确性风险优先级排序。本技能刻意与模式设计、查询/索引技能不重叠：它专注于原子性、隔离性、持久性、重试机制和一致性语义。

When to Apply

适用场景

Reference these guidelines when:

Implementing multi-document writes that must succeed or fail together
Choosing read concern / write concern for correctness guarantees
Handling transaction retry errors in application code
Diagnosing commit uncertainty and rollback risk
Running transactions on replica sets or sharded clusters
Designing idempotent business workflows with retries
Reviewing whether a workload actually needs a transaction

在以下场景中可参考本指南：

实现必须全部成功或全部失败的多文档写入
为保障正确性选择合适的read concern / write concern
在应用代码中处理事务重试错误
诊断提交不确定性与回滚风险
在副本集或分片集群上运行事务
设计支持重试的幂等业务工作流
评估某一工作负载是否确实需要事务

Non-Overlap Boundaries

非重叠边界

Schema shape decisions remain in
```
mongodb-schema-design
```
.
Index/query performance tuning remains in
```
mongodb-query-and-index-optimize
```
.
Vector/hybrid search patterns remain in
```
mongodb-ai
```
.
This skill covers correctness semantics and transaction-safe execution patterns.

模式结构决策归属于
```
mongodb-schema-design
```
技能范畴。
索引/查询性能调优归属于
```
mongodb-query-and-index-optimize
```
技能范畴。
向量/混合搜索模式归属于
```
mongodb-ai
```
技能范畴。
本技能专注于正确性语义与事务安全执行模式。

Rule Categories by Priority

按优先级划分的规则类别


fundamental-
consistency-
retry-
ops-
pattern-

Priority	Category	Impact	Prefix	Rules
1	Transaction Fundamentals	CRITICAL	`fundamental-`	5
2	Consistency Semantics	HIGH	`consistency-`	4
3	Retry and Error Handling	CRITICAL	`retry-`	4
4	Operational Constraints	HIGH	`ops-`	4
5	Implementation Patterns	MEDIUM	`pattern-`	3


fundamental-
consistency-
retry-
ops-
pattern-

优先级	类别	影响级别	前缀	规则数量
1	事务基础	关键	`fundamental-`	5
2	一致性语义	高	`consistency-`	4
3	重试与错误处理	关键	`retry-`	4
4	操作约束	高	`ops-`	4
5	实现模式	中	`pattern-`	3

Quick Reference

快速参考

1. Transaction Fundamentals (CRITICAL) - 5 rules

1. 事务基础（关键）- 5条规则

```
fundamental-use-transactions-when-required
```
- Use transactions for multi-document atomicity, not single-document writes
```
fundamental-propagate-session
```
- Pass the same session to every operation in a transaction
```
fundamental-one-transaction-per-session
```
- Run only one active transaction per session
```
fundamental-primary-read-preference
```
- Use primary read preference inside transactions
```
fundamental-commit-write-concern
```
- Set commit durability explicitly where business-critical

```
fundamental-use-transactions-when-required
```
- 仅在需要多文档原子性时使用事务，单文档写入无需事务
```
fundamental-propagate-session
```
- 事务中的所有操作必须使用同一个会话
```
fundamental-one-transaction-per-session
```
- 每个会话仅能运行一个活跃事务
```
fundamental-primary-read-preference
```
- 事务内部需使用主节点读取偏好
```
fundamental-commit-write-concern
```
- 对业务关键场景需显式设置提交持久性

2. Consistency Semantics (HIGH) - 4 rules

2. 一致性语义（高）- 4条规则

```
consistency-read-concern-levels
```
- Choose local, majority, or snapshot intentionally
```
consistency-snapshot-majority-coupling
```
- Understand snapshot visibility requirements
```
consistency-causal-majority-pairing
```
- Pair majority read+write for causal guarantees
```
consistency-rollback-risk
```
- Avoid weak concern combinations for critical workflows

```
consistency-read-concern-levels
```
- 按需选择local、majority或snapshot级别
```
consistency-snapshot-majority-coupling
```
- 理解快照可见性要求
```
consistency-causal-majority-pairing
```
- 搭配majority级别读与写以实现因果一致性保障
```
consistency-rollback-risk
```
- 关键工作流需避免弱一致性级别组合

3. Retry and Error Handling (CRITICAL) - 4 rules

3. 重试与错误处理（关键）- 4条规则

```
retry-transient-transaction-error
```
- Retry full transaction on transient transaction errors
```
retry-unknown-commit-result
```
- Retry commit safely when commit result is unknown
```
retry-transaction-too-large-cache
```
- Handle TransactionTooLargeForCache as a redesign signal
```
retry-upsert-duplicate-key-81
```
- Know retry behavior changes around duplicate-key upserts (7.0.22+, 8.0.11+, 8.1+)

```
retry-transient-transaction-error
```
- 遇到临时事务错误时重试整个事务
```
retry-unknown-commit-result
```
- 提交结果未知时安全重试提交操作
```
retry-transaction-too-large-cache
```
- 将TransactionTooLargeForCache错误视为需要重新设计的信号
```
retry-upsert-duplicate-key-81
```
- 了解重复键更新插入的重试行为变化（7.0.22+, 8.0.11+, 8.1+）

4. Operational Constraints (HIGH) - 4 rules

4. 操作约束（高）- 4条规则

```
ops-transaction-runtime-limit
```
- Keep transactions short and below lifetime limits
```
ops-lock-timeout-tuning
```
- Tune lock wait timeout for transactional lock acquisition
```
ops-restricted-operations
```
- Avoid unsupported operations inside transactions
```
ops-sharded-caveats
```
- Apply sharded-cluster transaction caveats explicitly

```
ops-transaction-runtime-limit
```
- 保持事务简短，不超过生命周期限制
```
ops-lock-timeout-tuning
```
- 调整事务锁获取的等待超时时间
```
ops-restricted-operations
```
- 避免在事务内部使用不支持的操作
```
ops-sharded-caveats
```
- 明确遵循分片集群的事务注意事项

5. Implementation Patterns (MEDIUM) - 3 rules

5. 实现模式（中）- 3条规则

```
pattern-withtransaction-vs-core-api
```
- Choose callback API vs core API intentionally
```
pattern-idempotent-transaction-body
```
- Make transaction bodies idempotent under retries
```
pattern-observability
```
- Instrument transaction outcomes and retry paths

```
pattern-withtransaction-vs-core-api
```
- 按需选择回调API或核心API
```
pattern-idempotent-transaction-body
```
- 确保事务主体在重试时具备幂等性
```
pattern-observability
```
- 为事务结果与重试路径添加监控埋点

Key Principle

核心原则

"Transactions are a correctness tool, not a default coding pattern."

Single-document writes are already atomic in MongoDB. Use transactions when business invariants span documents, collections, or shards.

“事务是一种正确性保障工具，而非默认编码模式。”

在MongoDB中，单文档写入本身已具备原子性。当业务约束跨文档、集合或分片时，才需要使用事务。

How to Use

使用方法

Read individual rule files for detailed explanations and code examples:

rules/fundamental-use-transactions-when-required.md
rules/retry-unknown-commit-result.md
rules/_sections.md

Each rule file contains:

Brief explanation of why it matters
Incorrect and correct code examples
When NOT to use the pattern
Verification checks and diagnostics

阅读单个规则文件获取详细说明与代码示例：

rules/fundamental-use-transactions-when-required.md
rules/retry-unknown-commit-result.md
rules/_sections.md

每个规则文件包含：

规则重要性的简要说明
错误与正确的代码示例
不适用该模式的场景
验证检查与诊断方法

How These Rules Work

规则工作机制

Recommendations with Verification

带验证的建议

Every rule in this skill provides:

A recommendation for correctness-safe behavior
A verification checklist for deployment reality
Commands to verify before implementation
MCP-friendly checks when connected

本技能中的每条规则都包含：

正确性安全行为建议
部署实际情况验证清单
实施前的验证命令
连接后的MCP友好检查项

Why Verification Matters

验证的重要性

I can reason about transaction semantics, but cannot infer your SLA, failure budget, or deployment topology without evidence. Always validate with your workload and cluster shape.

我可以分析事务语义，但如果没有具体信息，无法推断你的SLA、故障预算或部署拓扑。请始终结合你的工作负载与集群架构进行验证。

MongoDB MCP Integration

MongoDB MCP集成

For automatic verification, connect the MongoDB MCP Server:

Option 1: Connection String

json

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": ["-y", "mongodb-mcp-server", "--readOnly"],
      "env": {
        "MDB_MCP_CONNECTION_STRING": "mongodb+srv://user:pass@cluster.mongodb.net/mydb"
      }
    }
  }
}

Option 2: Local MongoDB

json

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": ["-y", "mongodb-mcp-server", "--readOnly"],
      "env": {
        "MDB_MCP_CONNECTION_STRING": "mongodb://localhost:27017/mydb"
      }
    }
  }
}

如需自动验证，请连接MongoDB MCP Server：

选项1：连接字符串

json

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": ["-y", "mongodb-mcp-server", "--readOnly"],
      "env": {
        "MDB_MCP_CONNECTION_STRING": "mongodb+srv://user:pass@cluster.mongodb.net/mydb"
      }
    }
  }
}

选项2：本地MongoDB

json

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": ["-y", "mongodb-mcp-server", "--readOnly"],
      "env": {
        "MDB_MCP_CONNECTION_STRING": "mongodb://localhost:27017/mydb"
      }
    }
  }
}

Action Policy

操作策略

I will NEVER execute write operations without your explicit approval.

Operation Type	MCP Tools	Action
Read (Safe)	`find` , `aggregate` , `explain` , `serverStatus` , `currentOp`	I may run automatically to verify
Write (Requires Approval)	`update` , `insert` , `delete` , `commitTransaction`	I will show the command and wait for your "yes"
Destructive (Requires Approval)	`drop` , `dropDatabase`	I will warn you and require explicit confirmation

未经你的明确批准，我绝不会执行任何写入操作。

操作类型	MCP工具	操作方式
读取（安全）	`find` , `aggregate` , `explain` , `serverStatus` , `currentOp`	我可能自动运行以进行验证
写入（需批准）	`update` , `insert` , `delete` , `commitTransaction`	我会展示命令并等待你确认“是”
破坏性操作（需批准）	`drop` , `dropDatabase`	我会发出警告并要求你明确确认

Full Compiled Document

完整编译文档

For the complete guide with all rules expanded:

AGENTS.md

包含所有规则详细说明的完整指南：

AGENTS.md