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

> Discover what database Macro uses. Macro leverages PostgreSQL (MacroDB) to store crucial data like documents, user accounts, projects, and communication history.

- Repository: [Macro/macro](https://github.com/macro-inc/macro)
- Tags: internals
- Published: 2026-08-21

---

**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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/services/document_storage_service/src/main.rs):

```rust
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`](https://github.com/macro-inc/macro/blob/main/crates/roles_and_permissions/src/outbound/pgpool.rs), this wrapper provides a clean interface for repository implementations:

```rust
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`](https://github.com/macro-inc/macro/blob/main/services/authentication_service/src/main.rs):

```rust
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.