Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
email_db_client
What it is
Part of the Email feature: the SQLx query crate for MacroDB's email tables — messages, threads, contacts, labels, links, attachments, sync tokens, CRM cleanup, and backfill.
Start here
src/lib.rs: the module list, one per table/feature area, mirroringmacro_db_client's layout.src/parse/: service↔DB type conversion (db_to_service.rs,service_to_db.rs) and column-length limits (column_limits.rs).README.md: local test-database setup.
Scope
- Owns: the
sqlx::query!call sites for email tables. - Not here: email domain/business logic →
crates/email; provider API calls →email_api_client. The schema lives incrates/macro_db_client/migrations/(shared MacroDB), not here.
Boundaries
- Depends on:
models_email,models_pagination,email_utils. - Used by:
crates/email,crates/search_service,services/calendar_service,services/authentication_service,services/search_processing_service,services/email_service.
Recipes
- Add a query to an existing table: the module in
src/<area>/(e.g.src/messages/get.rs) → itsmod.rs→ a fixture underfixtures/*.sqlif the test needs seed data. - Add a column or table: see
crates/macro_db_client/AGENTS.md(this crate only owns queries, not migrations).
Checks
cargo test -p email_db_client(SQLX_OFFLINEunset; requires local MacroDB —just setup_macrodb).
Parsed message responses expose the draft generation captured in the same SQL snapshot as their content.
Gotchas
Undated provider drafts use creation time for All Mail eligibility; spam/junk and trash remain excluded, including the timestamp override for synced Macro drafts. Keep ingestion, recomputation, and cached projections aligned.
Message deletion may return
Deferredwhile an accepted send owns the row; reconcile retained deletions under the message lock and compare both provider identity and draft generation.Resolve provider deletions with
get_simple_message_by_provider_and_link_for_updateinside the deletion transaction; retain the message lock through cleanup and deletion so Send completion or Undo cannot invalidate the snapshot.Scheduled delivery and durable Send share
email_draft_provider_attachment_idsfor native/forwarded identities, honoring removals and copied-upload deduplication.Forwarded-attachment delivery reads preserve
source_link_idfrom the original message; the destination draft inbox is only the query access scope.insert_message_with_txleaves labels with an unexpiredemail_gmail_pending_label_writesmarker, and the read and starred flags they drive, in their local state when it re-syncs a stored message. Given aResyncSnapshotfrom before the Gmail fetch, it changes only labels where Gmail disagrees with that snapshot, so a write made during the fetch stays.email_gmail_pending_label_writeskeeps one row per write on a message's label, newest byseq(staging order, which write ids need not follow). Only the newest row's write sends; older ones wait while a newer row hasn't expired, so abandoning a write can put the label back for the newest older write whose row hasn't expired (label_present) or the state before it (label_present_before, passed on by older writes given up). Code that stages, confirms or abandons a Gmail label write takeslock_thread_label_writesfor its threads first.The mailbox purge (
links::delete) is bound by storage latency: a 500-message batch reads about as many pages as its rows, TOAST and child rows occupy, so its time tracks per-read latency. A covering(link_id, thread_id, id)index for its walk only moves the SELECT's heap reads into the DELETE; it was benchmarked and rejected. A restarted purge rescans the dead index entries the earlier run left until vacuum can remove them.SQLx can't see that a column read through a
LEFT JOINinside aLATERALsubquery can be NULL and types it non-null from the table. Alias such columns"name?", and never force"name!"on one;from_contact_idis nullable andON DELETE SET NULL, so contact columns are often NULL.Quote and alias camelCase columns to Rust field names; check
crates/macro_db_client/migrations/for real column spelling, don't guess.A Macro draft (no provider id, or a live
email_mailbox_draftsrow) puts its thread in the inbox only whenemail_threads.has_received_mailis true.recompute_thread_metadataand the email crate'sthread_mail_projections_by_idsrestate this rule; change both together.
Related
Rules:
.agents/rules/rust/db.md· Docs:docs/development/database.mdScheduled-message reads and upserts preserve nullable agent correlation across delivery claims and retries.