import { getOsShortcut, Kbd } from "docs-ui"

export const metadata = { title: Database, }

{metadata.title}

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

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:

You can access the database settings from the command palette. Press <Kbd>{getOsShortcut()}</Kbd> + <Kbd>K</Kbd>, then select Storage.

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. Choose the "Storage" tab from the sidebar.
5. In the "Database read-only connection string" section, copy the read-only connection string in the code block.

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

psql "postgresql://..."

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

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.

Database write access should be used with caution as it allows direct modification of your database outside of your application. Only enable this feature if you understand the implications and need direct write access for specific tasks.

To enable database write access for an environment:

You can access the database settings from the command palette. Press <Kbd>{getOsShortcut()}</Kbd> + <Kbd>K</Kbd>, then select Storage.

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. Choose the "Storage" tab from the sidebar.
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.

Only organization owners can enable or disable database write access. If you can see the option to toggle write access, but it's disabled, contact your organization's owner to request access.

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

psql "postgresql://..."

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:

You can access the database settings from the command palette. Press <Kbd>{getOsShortcut()}</Kbd> + <Kbd>K</Kbd>, then select Storage.

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. Choose the "Storage" tab from the sidebar and find 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:

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

Make sure you're generating the database dump from PostgreSQL v16 and that pg_dump is compatible with that version.

• 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:

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.