Mastra Engine

The Mastra Engine is a PostgreSQL-based system that provides core infrastructure for AI applications built on Mastra. It handles data persistence, background processing, and vector search capabilities to help you run your AI workflows, syncs, and agents in a production-ready environment.

Mastra Engine is not required to run Mastra, but provides a “batteries-included” local development experience and a production-ready data layer.

Key Features

Data Persistence: Store agent states, records, conversation history, and other data required by your AI application.
Sync Infrastructure: Run sync tasks that load and merge data from various sources in a consistent manner.
Vector Search (RAG): Integrate vector stores for Retrieval-Augmented Generation (RAG) to build a knowledge base and query it for context.
Database Migrations & Type Generation: Automatically manage database schema and generate TypeScript types to ensure type safety.

Getting Started

Installation

Ensure you have Mastra and its CLI installed. Then add the engine package:

npm install @mastra/engine

Initialization

Initialize the Mastra Engine by passing in a database connection URL. This can be done when you set up your main Mastra instance:

import { Mastra } from "@mastra/core";
import { PostgresEngine } from "@mastra/engine";
 
export const mastra = new Mastra({
  engine: new PostgresEngine({
    url: process.env.DATABASE_URL!, // e.g., 'postgresql://localhost:5432/mydb'
  }),
  // ...other configuration
});

Once initialized, the Mastra Engine becomes available to all registered agents, workflows, tools, and syncs.

Core Concepts

Entities and Records

Entities represent a conceptual data model (like “Contacts”, “Orders”, or “Tickets”) in your application.
Records are individual data entries within an entity.

You can create, read, update, and delete entities and their records using the engine’s methods.

Sync Operations

Syncs are async functions that manage data synchronization between external systems and Mastra. For example, you can use a sync to import records from a third-party API into your local database.

RAG and Vector Search

With RAG (Retrieval-Augmented Generation), you can store document embeddings in the database and efficiently query them using vector search. The Mastra Engine can integrate with vector stores like PostgreSQL PgVector, Pinecone, or Qdrant. This allows your LLM to retrieve relevant context from your custom knowledge base.

CLI Commands

The Mastra CLI includes commands to manage your engine and database:

mastra engine add: Sets up your dev environment, starts Docker containers for Postgres, and configures .env.
mastra engine up: Starts your Docker containers as defined in your docker config file.
mastra engine migrate: Runs database migrations.
mastra engine generate: Generates TypeScript types from your database schema.
mastra engine down: Stops your Docker containers.

Example: Using the Mock Engine in Tests

For testing or development, you can use the MockMastraEngine:

import { MockMastraEngine } from "@mastra/core";
 
const mockEngine = new MockMastraEngine({ url: "mock://localhost" });
 
// Create an entity
const entity = await mockEngine.createEntity({
  name: "Contacts",
  connectionId: "user_123",
});
 
// Insert records
await mockEngine.upsertRecords({
  entityId: entity.id,
  records: [
    { externalId: "c1", data: { name: "Alice" }, entityType: "Contacts" },
    { externalId: "c2", data: { name: "Bob" }, entityType: "Contacts" },
  ],
});
 
// Query the records
const records = await mockEngine.getRecordsByEntityId({ entityId: entity.id });
console.log(records);

This mock engine mimics the behavior of the real engine without requiring a real database connection, making it ideal for unit tests.

Production Considerations

When running in production:

Connection Pooling: Ensure proper connection pooling and timeouts for your Postgres connection.
Migrations: Run mastra engine migrate during deployment to keep the schema up to date.
Backups: Regularly back up your Postgres database.
Observability: Use built-in telemetry and logging features in Mastra to monitor engine queries and performance.

API Summary

Entity Management:

createEntity({ name, connectionId }): Create a new entity
getEntityById({ id }): Get an entity by ID
getEntity({ name, connectionId }): Get entity by name and/or connectionId
deleteEntityById({ id }): Delete an entity and its associated records

Record Management:

upsertRecords({ entityId, records }): Insert or update records for an entity
getRecordsByEntityId({ entityId }): Retrieve all records for an entity
getRecordsByEntityName({ name, connectionId }): Retrieve all records for an entity by name and connectionId
getRecords({ entityName, connectionId, options }): Query records with filtering, sorting, and pagination

Sync Operations:

syncRecords({ name, connectionId, records, lastSyncId }): Sync incoming data to an entity

Vector Search (Future)

Integrate with vector stores for RAG workflows.

Conclusion

Mastra Engine is a key building block for building robust AI applications. By providing a standardized way to manage entities, records, and sync operations, it ensures a consistent and scalable data layer. Combined with Mastra’s workflows, agents, and observability tools, you can move from a prototype to a production-grade AI system with confidence.

Mastra Dev Syncs