Atomicity keeps a multi-step data operation consistent: every step succeeds together, or none of the changes take effect. It prevents partial writes from leaving conversations, indexes, or search data in a corrupted intermediate state. section 4.4.2 section 5.3.7
Apply atomicity when an operation changes several related records or artifacts:
- Insert every message in one database transaction, then update the session timestamp before committing. section 4.4.2
- Replace a document by deleting old chunks, extracting and chunking content, generating embeddings, and inserting replacements within one transactional boundary. section 5.3.7
- Treat document deletion as one operation across the document record, chunks, and vector store so partial deletion cannot leave orphaned search data. section 5.3.8
Atomic message persistence
A tool-assisted appointment conversation may produce a question, tool-call request, tool result, and final response. Insert them with one executemany call and commit once; if the connection fails or storage runs out, none are recorded. section 4.4.2
Listing 4.12 Adding messages to a session
def add_messages(
self,
session_id: str,
messages: List[Message]
) -> int:
cursor = self.conn.cursor()
cursor.executemany( #A
"""INSERT INTO messages
(session_id, role, content, tool_calls, tool_call_id,
➥timestamp)
VALUES
➥(%s, %s, %s, %s, %s, %s)""", #A
[
(
session_id,
msg.role,
msg.content,
json.dumps(msg.tool_calls)
➥if msg.tool_calls else None, #B
msg.tool_call_id,
msg.timestamp
)
for msg in messages
]
) #A
cursor.execute( #C
"UPDATE sessions SET updated_at =
➥%s WHERE session_id = %s", #C
(datetime.utcnow(), session_id) #C
) #C
self.conn.commit() #D
return len(messages)See the implementation pattern: batch message inserts, session timestamp update, and one final commit. section 4.4.2


















