Database

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

Managed Database Service on Cloud#

Medusa provisions and manages databases for each of your environments on Cloud.

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.

Cloud Database Configurations#

Medusa automatically configures the database for your environments on Cloud. 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.

Cloud Database Backups#

Medusa provides automatic backups for your environment databases on Cloud. The retention period depends on your plan:

You can upgrade your plan as explained in the Manage Plans guide.

To access the database backups of an environment:

1. If you're in a different organization, switch to the organization.
2. Click Projects in the sidebar and select the project that contains the environment you want to view.
3. In the project's dashboard, click on the name of the environment. For example, "Production".
4. Click Database in the sidebar under the environment's section.

The Database Backups section shows a table of available backups with the following columns:

• Generated At: When the backup was created.
• Source: The backup origin. Scheduled backups are created automatically; manual backups are triggered by you.
• Size: The backup file size.

Download a Backup#

To download a backup to your device:

1. In the Database Backups table, find the backup you want to download.
2. Click the icon and choose Download.

This will start a download of the backup file to your device. It is a .dump file that you can restore to a PostgreSQL database using tools like pg_restore. For example:

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

Restore a Backup#

To restore your database from a backup:

1. In the Database Backups table, find the backup you want to restore.
2. Click the icon and choose Restore.
3. In the confirmation dialog, type restore to confirm the action.
4. Click Restore backup to confirm.

Medusa notifies you when the restore completes or if an error occurs.

Trigger a Manual Backup#

A manual backup is triggered when you export a database dump from the environment settings. Learn how to do that in the Import/Export Cloud Database Dumps section below.

Connect to a Cloud Database#

In some cases, you may need to access your Cloud project's database directly, such as to export or import data.

Medusa gives you read access to your Cloud project's database, which is useful when you need to export data, perform analytics, or troubleshoot issues.

Get Read-Only Connection String#

To get the read-only connection string for an environment's database:

1. If you're in a different organization, switch to the organization.
2. Click Projects in the sidebar and select the project that contains the environment you want to view.
3. In the project's dashboard, click on the name of the environment. For example, "Production".
4. Click Database in the sidebar under the environment's section.
5. In the Database read-only connection string section, toggle read access on if it is not already enabled.
6. Copy the read-only connection string from the code block.

Then, you can connect to your database using a PostgreSQL client. For example, using the psql command-line tool:

Terminal
❯psql "postgresql://..."

After connecting to the database, you can run SQL queries to interact with your data.

Rotate Read Password#

You can rotate the password for the read-only connection string from the Database read-only connection string section. To do that:

1. Click the Rotate password button.
2. Confirm the action in the dialog that opens by clicking Rotate.

Medusa generates a new read-only connection string. Update any tools or scripts that use the old connection string after rotating.

Get Write Connection String#

All environments have a read-only connection string by default. This allows you to connect to the database and query data, but it doesn't allow you to modify the data or database schema. This is a security measure to prevent accidental changes to your database.

For advanced use cases where you need write access to your environment's database, such as importing data or performing maintenance tasks, Medusa allows organization owners to enable database write access.

To enable database write access for an environment:

1. If you're in a different organization, switch to the organization.
2. Click Projects in the sidebar and select the project that contains the environment you want to view.
3. In the project's dashboard, click on the name of the environment. For example, "Production".
4. Click Database in the sidebar under the environment's section.
5. In the Database write-access connection string section, toggle the switch to enable write access.
6. Once enabled, copy the write connection string from the code block that appears.

Then, you can connect to your database using a PostgreSQL client with the write connection string. For example, using the psql command-line tool:

Terminal
❯psql "postgresql://..."

Rotate Write Password#

Organization owners can rotate the password for the write connection string from the Database write-access connection string section. To do that:

1. Click the Rotate password button.
2. Confirm the action in the dialog that opens by clicking Rotate.

Medusa generates a new write connection string. Update any tools or scripts that use the old connection string after rotating.

Import/Export Cloud Database Dumps#

Medusa allows you to export and import database dumps for any environment on Cloud. 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. If you're in a different organization, switch to the organization.
2. Click Projects in the sidebar and select the project that contains the environment you want to view.
3. In the project's dashboard, click on the name of the environment. For example, "Production".
4. Click Database in the sidebar under the environment's section.

In the "Database dump" 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

Change Preview Environment Database#

By default, when Medusa creates a preview environment on Cloud, 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.

Running Migrations on Cloud#

Medusa automatically runs database migrations for every deployment on Cloud. This ensures that your database schema is always up-to-date with the latest changes in your Medusa application.

When you deploy changes to an environment on Cloud, Medusa:

1. Runs any pending database migrations.
2. Syncs links.
3. Runs pending data migration scripts.

So, if you define new database migrations in your module, define new links, or add data migration scripts, Medusa will apply those changes automatically when you deploy the changes to Cloud.

You don't need to add a predeploy script to your package.json, or run medusa db:migrate in your start script, to apply migrations on Cloud. If you're moving a self-hosted application that runs migrations this way, remove the medusa db:migrate command from your start script.

How Data Migration Scripts Run on Cloud#

Each environment has its own database, so Medusa runs a data migration script once per environment. So:

• A script that completed in a previous deployment doesn't run again in later deployments.
• A script that throws an error, or that was interrupted, runs again in the next deployment until it completes successfully.

Run One-Off Data Scripts on Cloud#

To run a one-off data task on a Cloud environment, such as seeding data or filling a configuration table, create a data migration script in the src/migration-scripts directory instead of a custom CLI script that you run with medusa exec.

For example:

src/migration-scripts/seed-config.ts
1import { ExecArgs } from "@medusajs/framework/types"2
3export default async function seedConfig({4  container,5}: ExecArgs) {6  // perform the data changes7  // by running a workflow8}

When you deploy the commit that adds the script, Medusa runs it during the deployment and doesn't run it again in that environment's later deployments.