docs: add cloud database guides (#12758)
* docs: add cloud database guides * fixes * fixes * small fix
This commit is contained in:
Shahed Nasser
GitHub
112
www/apps/cloud/app/database/page.mdx
Normal file
112
www/apps/cloud/app/database/page.mdx
Normal file
@@ -0,0 +1,112 @@
|
||||
export const metadata = {
|
||||
title: `Database`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
In this guide, you'll learn about the managed database service that Cloud provides as part of your project environments.
|
||||
|
||||
## Managed Database Service
|
||||
|
||||
Cloud offers a managed PostgreSQL database service for your project environments. Each environment has its own dedicated database that is automatically provisioned when the environment is created.
|
||||
|
||||
So, when you create a new project, Cloud creates a production database for the production environment. If you create a staging environment, Cloud creates a separate database for that environment as well.
|
||||
|
||||
This isolation between environment databases allows you to safely make or test changes in environments without affecting one another, especially the production environment and its data.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Database Configurations
|
||||
|
||||
Cloud 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
|
||||
|
||||
Cloud 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. Cloud 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
|
||||
|
||||
Cloud 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](../organizations/page.mdx), 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:
|
||||
|
||||
```bash
|
||||
pg_dump -Fc -d postgres://postgres:secret@localhost:5432/mydatabase -f mydata.dump
|
||||
```
|
||||
|
||||
<Note>
|
||||
|
||||
Make sure you're generating the database dump from PostgreSQL v16 and that [pg_dump](https://www.postgresql.org/docs/16/app-pgdump.html) is compatible with that version.
|
||||
|
||||
</Note>
|
||||
|
||||
- **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:
|
||||
|
||||
```bash
|
||||
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](!docs!/learn/fundamentals/api-routes) 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](!docs!/learn/fundamentals/api-routes/protected-routes).
|
||||
- Create a secret API key for a user using the [Medusa Admin](!user-guide!/settings/developer/secret-api-keys#create-secret-api-key).
|
||||
- Call the API route to perform database operations, [passing the API key in the header](!api!/admin#2-api-token). For example, to send the request in a Node.js application:
|
||||
|
||||
```ts
|
||||
const api_key_token = "YOUR_API_KEY"
|
||||
fetch(`https://my-project.medusajs.app/admin/my-route`, {
|
||||
headers: {
|
||||
Authorization: `Basic ${
|
||||
Buffer.from(`${api_key_token}:`).toString("base64")
|
||||
}`,
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
Where:
|
||||
|
||||
- `YOUR_API_KEY` is the secret API key you created.
|
||||
- `my-project.medusajs.app` is the [environment's URL](../deployments/page.mdx#find-environments-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 Cloud creates a [preview environment](../environments/page.mdx#preview-environments), 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 [Environments](../environments/page.mdx#manage-shared-previews-settings) guide.
|
||||
@@ -1,4 +1,5 @@
|
||||
import { Table } from "docs-ui"
|
||||
import { Table, InlineIcon } from "docs-ui"
|
||||
import { EllipsisHorizontal } from "@medusajs/icons"
|
||||
|
||||
export const metadata = {
|
||||
title: `Deployments`,
|
||||
@@ -273,4 +274,32 @@ To redeploy a deployment:
|
||||
|
||||
This will trigger the redeployment process for the selected deployment. The deployment will go through [the same lifecycle](#deployment-statuses-and-lifecycle) as a new deployment.
|
||||
|
||||
Once the redeployment is complete, the deployment's status will change to "Live" and it will become the new live version of the environment.
|
||||
Once the redeployment is complete, the deployment's status will change to "Live" and it will become the new live version of the environment.
|
||||
|
||||
---
|
||||
|
||||
## Change Deployment Rules
|
||||
|
||||
For each environment, you can change the rules that trigger a new deployment. For example, you can change the branch that the environment is connected to, which changes when a new deployment is created.
|
||||
|
||||
<Note>
|
||||
|
||||
Changing the branch associted with an environment only works for long-lived environments.
|
||||
|
||||
</Note>
|
||||
|
||||
To change the deployment rules for an environment:
|
||||
|
||||
1. [Go to the environment's dashboard](#find-environment-deployments).
|
||||
2. Click on the "Settings" tab.
|
||||
3. Scroll down to the "Deployment rules" section. You'll find a `branch` rule in this section.
|
||||
|
||||
|
||||
|
||||
4. You can edit it by clicking the <InlineIcon Icon={EllipsisHorizontal} alt="three-dots" /> icon and choosing "Edit" from the dropdown.
|
||||
5. In the side window that opens, you can change the branch that the environment is connected to. For example, you can change it from `main` to `staging` to create a new deployment every time you push a commit to the `staging` branch.
|
||||
6. Click "Save" to apply the changes.
|
||||
|
||||
The deployment rules will take effect for next deployments. For example, if you change the branch to `staging`, the next deployment will be created from the latest commit in the `staging` branch.
|
||||
|
||||
|
||||
|
||||
@@ -262,11 +262,27 @@ You can rename the file to `.env` and use it in your local development.
|
||||
|
||||
---
|
||||
|
||||
## Manage Environment's Deployment Rules
|
||||
## Change Environment's Branch
|
||||
|
||||
<Note>
|
||||
|
||||
You can't change the branch of preview environments. This section only applies to long-lived environments, such as Production or Staging.
|
||||
|
||||
</Note>
|
||||
|
||||
In an environment's "Settings" tab, you can manage the deployment rules for the environment. Deployment rules allow you to control how and when deployments are triggered for the environment.
|
||||
|
||||
Learn more in the [Deployments](#) guide.
|
||||
To change the branch associated with an environment using deployment rules:
|
||||
|
||||
1. In the [environment's dashboard](#open-environment-dashboard), click on the "Settings" tab.
|
||||
2. In the "Deployment rules" section, click the <InlineIcon Icon={EllipsisHorizontal} alt="three-dots" /> icon at the right side of the `branch` rule.
|
||||
3. Choose "Edit" from the dropdown menu.
|
||||
4. In the side window that opens, you can change the branch associated with the environment.
|
||||
5. Once you're done, click the "Save" button.
|
||||
|
||||
Changes will take effect the next time you push a commit to the new branch. The environment will be redeployed with the latest changes from the new branch.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
@@ -323,7 +339,7 @@ To open a preview environment's dashboard:
|
||||
1. Go to its [project's dashboard](../projects/page.mdx#open-project-dashboard).
|
||||
2. In the "Previews" card, click on the preview environment you want to view.
|
||||
|
||||
Then, you can manage the preview environment just like any other long-lived environment, as mentioned throughout this guide. You can [manage its environment variables](#manage-environment-variables), [deployment rules](#manage-environments-deployment-rules), and [import/export its database dump](#import-and-export-environments-database-dump).
|
||||
Then, you can manage the preview environment just like any other long-lived environment, as mentioned throughout this guide. You can [manage its environment variables](#manage-environment-variables) and [import/export its database dump](#import-and-export-environments-database-dump).
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -2,8 +2,9 @@ export const generatedEditDates = {
|
||||
"app/page.mdx": "2025-06-12T12:31:48.681Z",
|
||||
"app/organization/page.mdx": "2025-06-12T14:43:20.772Z",
|
||||
"app/projects/page.mdx": "2025-06-17T11:20:16.174Z",
|
||||
"app/environments/page.mdx": "2025-06-17T11:12:50.824Z",
|
||||
"app/environments/page.mdx": "2025-06-17T14:29:55.288Z",
|
||||
"app/deployments/page.mdx": "2025-06-17T11:17:03.236Z",
|
||||
"app/organizations/page.mdx": "2025-06-17T10:48:50.969Z",
|
||||
"app/notifications/page.mdx": "2025-06-17T12:29:18.819Z"
|
||||
"app/notifications/page.mdx": "2025-06-17T12:29:18.819Z",
|
||||
"app/database/page.mdx": "2025-06-17T14:34:57.104Z"
|
||||
}
|
||||
@@ -55,6 +55,23 @@ export const generatedSidebars = [
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"loaded": true,
|
||||
"isPathHref": true,
|
||||
"type": "category",
|
||||
"title": "Resources",
|
||||
"initialOpen": true,
|
||||
"children": [
|
||||
{
|
||||
"loaded": true,
|
||||
"isPathHref": true,
|
||||
"type": "link",
|
||||
"title": "Database",
|
||||
"path": "/database",
|
||||
"children": []
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"loaded": true,
|
||||
"isPathHref": true,
|
||||
|
||||
@@ -39,6 +39,18 @@ export const sidebar = [
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
type: "category",
|
||||
title: "Resources",
|
||||
initialOpen: true,
|
||||
children: [
|
||||
{
|
||||
type: "link",
|
||||
title: "Database",
|
||||
path: "/database",
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
type: "category",
|
||||
title: "Monitoring & Support",
|
||||
|
||||
Reference in New Issue
Block a user