Database

In this guide, you'll learn about the managed database service that Medusa provides as part of your project environments.

Managed Database Service#

Medusa provisions and manages databases for each of your environments.

Each project environment has a dedicated PostgreSQL database. These databases are entirely isolated from one another.

This isolation allows you to safely make or test changes in environments without affecting one another, especially the production environment and its data.

Database Configurations#

Medusa automatically configures the database for your environments. So, you don't need to worry about setting up the database, configuring it with your Medusa application, or monitoring performance and availability on your end.

Database Backups#

Medusa provides automatic backups for your environment databases. These backups are retained for 14 days and allow you to restore your database to a previous state, if needed.

If you need to restore a database backup, you can contact support to request a point-in-time recovery. This is useful if you accidentally delete data or need to revert changes made to the database.

Accessing the Database#

In some cases, you may need to access the database directly, such as to export or import data. However, since Cloud is a managed service, you can't directly access your database. Medusa also doesn't expose the database connection details.

This section provides alternative ways to interact with your database based on your needs.

Option 1: Database Dump#

Medusa allows you to export and import database dumps for any environment. This is useful for seeding the database with initial data, migrating from other hosting platforms, or debugging issues locally.

To import or export a database dump for an environment:

1. From the organization's dashboard, click on the environment's project.
2. In the project's dashboard, click on the name of the environment. For example, "Production".
3. In the environment's dashboard, click on the "Settings" tab.
4. Scroll down to the "Database dump" section.

In this section, you can either:

• Import: Upload a database dump file to import data into the environment's database. You can generate a database dump using pg_dump. For example:

Terminal
❯pg_dump -Fc -d postgres://postgres:secret@localhost:5432/mydatabase -f mydata.dump

• Export: Download the current database as a dump file. You'll then receive a notification once the export is ready for download. Then, you can restore the database dump locally using pg_restore. For example:

Terminal
❯pg_restore --no-acl --no-owner --no-privileges --clean --if-exists -d 'postgres://postgres:secret@localhost:5432/mydatabase' mydata.dump

Option 2: Custom API Routes#

In some cases, you may need more flexibility interacting with the database. For example, you might need to retrieve specific data for analysis, or update data coming from an external source.

To interact with an environment's database with more flexibility, you can:

• Create a custom API route that retrieves or updates data in the database.
  • Make sure to create the API route under the /admin prefix, or protect the API route with an API key.
• Create a secret API key for a user using the Medusa Admin.
• Call the API route to perform database operations, passing the API key in the header. For example, to send the request in a Node.js application:

Code
1const api_key_token = "YOUR_API_KEY"2fetch(`https://my-project.medusajs.app/admin/my-route`, {3  headers: {4    Authorization: `Basic ${5      Buffer.from(`${api_key_token}:`).toString("base64")6    }`,7  },8})

Where:

• YOUR_API_KEY is the secret API key you created.
• my-project.medusajs.app is the environment's URL.
• my-route is the path to the custom API route you created.

This approach allows you to perform any database operations you need, such as retrieving or updating data, without directly accessing the database.

Change Preview Environment Database#

By default, when Medusa creates a preview environment, it replicates the Production database. This allows you to test changes in a safe environment that mirrors production, without affecting the live data.

Cloud also allows you to configure which environment's database to replicate the preview database from. For example, you can replicate the Staging environment's database instead of Production.

Learn more in the Preview Environments guide.