# How to Generate IDs in Macro Rust Code: UUIDv7 Patterns and Examples

> Learn to generate UUIDv7 IDs in Rust macro code using macro_uuid generate_uuid_v7. Explore patterns and examples from the macro-inc/macro repository.

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

---

**Use `macro_uuid::generate_uuid_v7()` to create new time-ordered identifiers and `macro_uuid::string_to_uuid()` to parse string representations, as implemented across the macro-inc/macro repository.**

The Macro codebase standardizes on UUID version 7 for all primary keys and entity identifiers. This approach ensures monotonic, sortable IDs that perform well in database indexes and distributed systems. The `macro_uuid` helper crate provides the canonical interface for all ID operations, abstracting away the underlying `uuid` crate details.

## The Core macro_uuid API

The repository centralizes identifier generation through two primary functions exported by the `macro_uuid` crate. These functions guarantee consistent formatting and error handling across services.

### Generating New UUIDs with generate_uuid_v7

The `generate_uuid_v7()` function returns a `uuid::Uuid` instance encoded as version 7. This variant embeds a Unix timestamp in the most significant bits, producing time-ordered values that sort naturally by creation time.

```rust
use macro_uuid::generate_uuid_v7;

// Creates a new, unique, time-ordered identifier
let new_entity_id = generate_uuid_v7();

```

According to the source analysis, this pattern appears in [`services/email_service/src/util/upload_attachment.rs`](https://github.com/macro-inc/macro/blob/main/services/email_service/src/util/upload_attachment.rs) at line 109:

```rust
let attachment_sfs_id = macro_uuid::generate_uuid_v7();

```

The function is also invoked in [`services/scheduled_action/src/outbound/tokio_dispatcher.rs`](https://github.com/macro-inc/macro/blob/main/services/scheduled_action/src/outbound/tokio_dispatcher.rs) and [`services/search_processing_service/src/process/document/raw_document.rs`](https://github.com/macro-inc/macro/blob/main/services/search_processing_service/src/process/document/raw_document.rs) at line 301 for document processing workflows.

### Parsing String IDs with string_to_uuid

When handling external input or seed data, use `string_to_uuid()` to convert string representations into typed UUIDs. This function returns a `Result<Uuid, ParseError>`, requiring explicit error handling.

In [`tooling/seed_cli/src/service/db/mod.rs`](https://github.com/macro-inc/macro/blob/main/tooling/seed_cli/src/service/db/mod.rs) at line 220, the codebase unwraps the result for trusted seed data:

```rust
&macro_uuid::string_to_uuid(item_id).unwrap(),

```

For production API endpoints, map the error to the application's error type:

```rust
let entity_uuid = macro_uuid::string_to_uuid(entity_id)
    .map_err(|e| anyhow::anyhow!("entity id {entity_id} is not a uuid: {e:?}"))?;

```

## Production Code Examples from the Macro Repository

The following file paths demonstrate the canonical patterns for ID generation in different contexts:

**Attachment Creation** — [`services/email_service/src/util/upload_attachment.rs`](https://github.com/macro-inc/macro/blob/main/services/email_service/src/util/upload_attachment.rs)

```rust
// Line 109: Generates a fresh ID for file storage references
let attachment_sfs_id = macro_uuid::generate_uuid_v7();

```

**Database Seeding** — [`tooling/seed_cli/src/service/db/mod.rs`](https://github.com/macro-inc/macro/blob/main/tooling/seed_cli/src/service/db/mod.rs)

```rust
// Line 220: Converts seed fixture IDs into database-compatible UUIDs
let parsed_id = macro_uuid::string_to_uuid(item_id).unwrap();

```

**Team Repository** — [`crates/teams/src/outbound/team_repo.rs`](https://github.com/macro-inc/macro/blob/main/crates/teams/src/outbound/team_repo.rs)
The codebase uses `generate_uuid_v7()` at line 99 when persisting new team records, ensuring time-ordered identifiers for pagination queries.

**Scheduled Actions** — [`services/scheduled_action/src/outbound/tokio_dispatcher.rs`](https://github.com/macro-inc/macro/blob/main/services/scheduled_action/src/outbound/tokio_dispatcher.rs)
Dispatches actions using `generate_uuid_v7()` to assign deterministic, traceable job IDs without external randomness overhead.

## Database Integration and Error Handling

When inserting records with SQLx, pass the `Uuid` directly as a bind parameter. The `macro_uuid` functions return the standard `uuid::Uuid` type, compatible with SQLx's `query!` macro:

```rust
use macro_uuid::generate_uuid_v7;
use sqlx::query;

let new_id = generate_uuid_v7();

query!(
    "INSERT INTO documents (id, title) VALUES ($1, $2)",
    new_id,
    title
)
.execute(&pool)
.await?;

```

For parsing user-supplied IDs in API handlers, always propagate parsing errors rather than unwrapping:

```rust
let thread_uuid = macro_uuid::string_to_uuid(&thread_id)
    .map_err(|_| ApiError::InvalidIdFormat)?;

```

## Summary

- **Always use `macro_uuid::generate_uuid_v7()`** for new primary keys to ensure time-ordered, database-friendly identifiers.
- **Use `macro_uuid::string_to_uuid()`** when converting external string input to UUID types, handling the `Result` appropriately for the context.
- **Reference implementation files** such as [`services/email_service/src/util/upload_attachment.rs`](https://github.com/macro-inc/macro/blob/main/services/email_service/src/util/upload_attachment.rs) and [`tooling/seed_cli/src/service/db/mod.rs`](https://github.com/macro-inc/macro/blob/main/tooling/seed_cli/src/service/db/mod.rs) for copy-paste patterns.
- **Avoid `uuid::Uuid::new_v4()`** in new code; the Macro codebase standardizes on v7 for performance and sortability benefits.

## Frequently Asked Questions

### What is the correct function to generate new IDs in Macro Rust code?

Use `macro_uuid::generate_uuid_v7()`. This function creates UUID version 7 values that include a timestamp component, making them naturally sortable by creation time. The repository uses this exclusively in [`crates/teams/src/outbound/team_repo.rs`](https://github.com/macro-inc/macro/blob/main/crates/teams/src/outbound/team_repo.rs) and [`services/email_service/src/util/upload_attachment.rs`](https://github.com/macro-inc/macro/blob/main/services/email_service/src/util/upload_attachment.rs) rather than random UUIDv4.

### How do I convert a string ID to a UUID type in the Macro codebase?

Call `macro_uuid::string_to_uuid(input_str)`. This returns a `Result<Uuid, _>` that you must handle. In seed scripts like [`tooling/seed_cli/src/service/db/mod.rs`](https://github.com/macro-inc/macro/blob/main/tooling/seed_cli/src/service/db/mod.rs), developers often unwrap trusted data, while API endpoints should map errors to HTTP 400 responses.

### Why does Macro Rust use UUIDv7 instead of UUIDv4?

UUIDv7 encodes a Unix timestamp in the high bits of the identifier, producing values that sort chronologically without additional timestamp columns. This improves database index locality and enables efficient time-based pagination, which is why [`services/search_processing_service/src/process/document/raw_document.rs`](https://github.com/macro-inc/macro/blob/main/services/search_processing_service/src/process/document/raw_document.rs) relies on `generate_uuid_v7()`.

### Where can I find working examples of ID generation patterns?

Examine [`services/email_service/src/util/upload_attachment.rs`](https://github.com/macro-inc/macro/blob/main/services/email_service/src/util/upload_attachment.rs) for new ID creation, [`tooling/seed_cli/src/service/db/mod.rs`](https://github.com/macro-inc/macro/blob/main/tooling/seed_cli/src/service/db/mod.rs) for string-to-UUID conversion, and [`services/scheduled_action/src/outbound/tokio_dispatcher.rs`](https://github.com/macro-inc/macro/blob/main/services/scheduled_action/src/outbound/tokio_dispatcher.rs) for background job identifier assignment. These files demonstrate the production-ready patterns approved for the Macro codebase.