What Database Does Macro Use and What Data Does It Store?

TLDR: Macro uses PostgreSQL (referred to internally as MacroDB) as its primary relational datastore, storing documents, user accounts, projects, communication history, email content, and notification preferences.

The Macro platform persists its core business data in a centralized PostgreSQL instance known throughout the codebase as MacroDB. This database serves as the single source of truth for both user-facing features and internal services, handling everything from raw document storage to real-time messaging metadata. Understanding what data Macro stores and how it is structured is essential for developing against the macro_db_client interfaces or contributing to services like authentication and document storage.

MacroDB: The PostgreSQL Foundation

According to the architecture overview in CLAUDE.md, MacroDB is explicitly defined as the main PostgreSQL database for the platform【https://github.com/macro-inc/macro/blob/main/CLAUDE.md#L42-L44】. The system leverages the sqlx crate for asynchronous, type-safe SQL queries in Rust, ensuring compile-time verification of database interactions.

What Data Does MacroDB Store?

MacroDB holds five primary categories of business-critical data:

• Documents – Raw files and their associated metadata.
• Users & Projects – Account information, project definitions, and permission mappings.
• Communication data – Messages, channels, participants, and thread histories.
• Email content – Email threads, individual messages, and related metadata.
• Notification preferences & history – Users' notification settings and a log of notifications sent.

How MacroDB Is Implemented in the Codebase

Database Client Architecture

Schema management and query definitions are centralized in the macro_db_client crate. According to the crate's documentation, this module contains the migration files and Rust wrappers used to interact with MacroDB via sqlx【https://github.com/macro-inc/macro/blob/main/crates/macro_db_client/README.md】.

Connection Pool Setup

Services obtain connections to MacroDB using PgPoolOptions from the sqlx library. This pattern appears consistently across service entry points, such as in services/document_storage_service/src/main.rs:

use sqlx::postgres::PgPoolOptions;

let db = PgPoolOptions::new()
    .max_connections(5)
    .connect(&std::env::var("DATABASE_URL")?)
    .await?;

The MacroDB Wrapper

To enforce type safety and standardize access patterns, the codebase wraps the raw PgPool in a dedicated MacroDB struct. Defined in crates/roles_and_permissions/src/outbound/pgpool.rs, this wrapper provides a clean interface for repository implementations:

use sqlx::PgPool;

pub struct MacroDB {
    pool: PgPool,
}

impl MacroDB {
    pub fn new(pool: PgPool) -> Self {
        Self { pool }
    }
}

Service Integration

Services consume the MacroDB wrapper through dependency injection. The authentication service, for instance, instantiates separate MacroDB instances for user and project repositories as shown in services/authentication_service/src/main.rs:

let user_roles_and_permissions_macro_db = MacroDB::new(db.clone());
let user_roles_and_permissions_service = UserRolesAndPermissionsServiceImpl {
    user_repo: user_roles_and_permissions_macro_db.clone(),
    project_repo: user_roles_and_permissions_macro_db,
};

Summary

• Macro uses PostgreSQL (MacroDB) as its primary relational data store.
• MacroDB persists documents, users, projects, communications, emails, and notifications.
• The macro_db_client crate centralizes schema migrations and sqlx query definitions.
• Services connect via PgPoolOptions and wrap connections in the MacroDB struct for type-safe repository access.
• Database connection strings are sourced from the DATABASE_URL environment variable.

Frequently Asked Questions

Is MacroDB a separate database product or a custom engine?

MacroDB is not a custom database engine. It is the internal name for the standard PostgreSQL instance used by the Macro platform. The codebase interacts with it using the sqlx Rust crate, treating it as a conventional relational database.

How does Macro handle database schema migrations?

Migrations are managed by the macro_db_client crate, which houses the migration files and Rust wrappers for all MacroDB interactions. This centralization ensures that schema changes are tracked alongside the query logic that depends on them.

Can I connect to MacroDB using standard PostgreSQL tools?

Yes. Since MacroDB is a standard PostgreSQL database, you can connect using any PostgreSQL client (such as psql, pgAdmin, or DataGrip) using the DATABASE_URL connection string configured for the services.

What Rust crate does Macro use for database access?

Macro uses sqlx for compile-time checked SQL queries. Services create connection pools using PgPoolOptions and wrap them in the internal MacroDB struct to expose repository methods used by the authentication_service, document_storage_service, and other components.

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