Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
macro_db_client
What it is
Belongs to shared infrastructure: the database client crate for MacroDB (Postgres), owning its migrations and most of the compile-time-checked queries used across Rust services.
Start here
src/lib.rs: the module list — one module per table/feature area (user.rs,document.rs,organization.rs,team/,item_access/, ...).migrations/: MacroDB's SQLx-generated migrations, 500+ files; the only place MacroDB schema changes are made.tests/: cross-table integration tests (e.g.add_forms.rs).
Scope
- Owns: MacroDB's schema (
migrations/) and thesqlx::query!call sites for the tables listed insrc/lib.rs. - Not here: domain logic, authorization decisions, or caching built on top of these queries — those live in the owning domain crate/service that calls in.
agent_session_notification is an additive leased outbox owned by
agent_session. Review adapters use its transaction-aware producer port;
notification frames have their own log direction. Session deletion cascades
outbox rows, and migrations retain compatibility with prior table writers.
The agent-session notification migration backfills legacy review outcomes and bridges old-producer writes during rollout; keep that bridge until legacy review producers have retired. Encode empty legacy item lists as JSON arrays so the typed notification reader can decode them.
The agent_session.turn_state constraint includes failed for terminal turn
errors; extend it additively before services begin writing new turn states.
Install widened checks as NOT VALID and validate in a separate migration so
the scan does not retain the replacement migration's exclusive table lock.
Boundaries
- Depends on:
entity_access_db_utils,entity_registry_db_utils,models_permissions,models_entity_access_management,model,model-entity. - Used by: most Rust services and several domain crates (e.g.
documents,ai_tools,authentication_service,email_service); a query here is widely shared — check callers before changing a function's signature.
Recipes
Add a column or table:
sqlx migrate add --source crates/macro_db_client/migrations <name>→ edit the generated SQL file(s) → the module insrc/<area>.rs(orsrc/<area>/) →nix develop --command just prepare_db.Add a query to an existing table: the module in
src/<area>.rs→ its tests →nix develop --command just prepare_dbif cache metadata is missing.Add a new owned area:
src/<area>.rs→pub mod <area>;insrc/lib.rs→ gate it behind a Cargo feature inCargo.tomlonly if it's optional (seeaccount_merge_request,team).Composed-memory tables and refresh leases are owned by
crates/memory; migrations leave legacy memory rows intact.
Checks
cargo test -p macro_db_client(SQLX_OFFLINEunset; requires local MacroDB —just setup_macrodb).- After schema or query changes:
nix develop --command just prepare_dbfrom the repo root, then commit the regenerated root.sqlx/.
agent_external_replies stores external runtime reply destinations and outcomes;
its queries and recovery policy belong to agent_harness. Its creation time is
stable across retries, and announced records successful pending-message posts.
The additive migrations are compatible with older service binaries; session
deletion cascades its rows.
agent_preview_* stores preview-specific ownership, credential hashes and
watchers; its queries and policy belong to agent_preview. Leases have a bounded
TTL, deletion cascades credentials, and sweepers reclaim expired watchers and
unreferenced replicas. These additive tables do not change agent-session claims.
Gotchas
Migrations deploy before service code: never drop a column/table in the same PR that removes its last usage (see
docs/development/database.md).call_participants.clientdefaults topersonfor older call writers; programmatic joins setagentorapi_keyafter recording attendance.Never hand-edit
.sqlx/query-*.jsonor invent a migration timestamp.Keep concurrent index migrations to one statement with
-- no-transaction; build replacement indexes before dropping old constraints, and validate large table checks in a later transaction. See the Outlook rollout notes indocs/design/outlook-email-support.mdfor failure recovery and deployment order.Quote and alias camelCase columns to Rust field names (
SELECT "userId" AS user_id); don't guess spelling — checkmigrations/.Saved-view sharing uses current team membership and chronological owner/team indexes. Deploy additive revision and team-share columns before service changes. Keep permanent
saved_view_tombstoneIDs and the deletion trigger to prevent delayed creates from resurrecting deleted definitions. Use a fresh disposable database when checking replacement branch migrations.External chats (
external_chat*tables: chats, people, messages, attachments, reactions, poll votes, read state) are provider-neutral; WhatsApp keeps its account, pairing, roster, chat list, membership, alias, observation, receipt and send tables (whatsapp_*). Domain queries live inexternal_chat(generic tables) andwhatsapp_linked(whatsapp_*tables and ingest).
Related
- Rules:
.agents/rules/rust/db.md,.agents/rules/rust/architecture.md· Docs:docs/development/database.md· Skill:dump-schema
Email send migrations add email_messages.draft_generation and attempt handle/inbox
fences. Deploy the additive migrations and all generation-aware writers before
enabling the independent email outbox; old writers do not enforce these fences.
preserve_deleted_email_send_delivery defers active-send deletion before compacting
content. Bypass retention for inboxes marked deleting_at and direct inbox
cascades; other parent cascades must not destroy unresolved delivery state. Deferred markers retain provider identity and
draft generation so Undo/resend cannot inherit an old deletion.
The import ledger accepts Jira Cloud sources with jira_issue, jira_project
and jira_epic kinds. Jira has its own concurrent partial team-claim index; source
and kind constraints expand without rewriting existing rows and validate separately.
crm_pipeline_stage_requirements stores pipeline-owned rules keyed by stage
column, option and required column IDs. Foreign-key cascades remove rules when
any referenced stage, field or pipeline is explicitly deleted; renames preserve them.
mcp_oauth_* tables hold the public MCP OAuth broker's state (registrations,
refresh token bindings, pending authorizations, issued codes); their queries and
expiry sweep belong to mcp_auth_proxy. Rows carry expires_at and have no
foreign keys; the broker deletes expired rows.
Spam/Trash candidate indexes cover
email_messages(link_id, id)only for the corresponding positivemailbox_stateJSON containment predicate; keep query literals aligned with the partial-index predicates.If either concurrent folder-index migration is interrupted, inspect
pg_index.indisvalidand drop only its invalid index before retrying;CREATE INDEX IF NOT EXISTSwould silently preserve an unusable index.agent_correlationowns invocation mappings; activity and scheduled-email correlation columns remain nullable for older writers. Build the activity correlation index concurrently, outside a transaction.