How To Add An External Database To Strapi Cloud

Strapi Cloud provides a pre-configured PostgreSQL database by default. However, you can also configure it to utilize an external SQL database, if needed.

Learn how to add an external database to your Strapi Cloud account. Although this is a supported feature, it is not something we recommend unless you have a specific reason for doing so. This is because Strapi Cloud provides a managed database that is optimized for Strapi.

Using an external database may result in unexpected behavior and/or performance issues (e.g., network latency may impact performance). Strapi cannot provide security or support with configuring external databases.

Caveats

• It may impact the performance of running SQL connection over the public internet.
• Network latency. Choose a data center closer to your cloud region.
• Security is your responsibility.
• No support from Strapi Cloud SE

We recommend using the default Strapi Cloud database for most users because it is optimized for Strapi.

But, in your case, you need to use an external database, so let's see how we can set one up on our cloud account.

Prerequisites

1. Local Strapi project.
2. The same project deployed to Strapi Cloud.
3. Credential for an external database.
4. If using an existing database, the schema must match the Strapi project schema.

You can watch the following video on deploying a new Strapi Project to the cloud. But in this example, I already have a project running locally on my computer.

I have a local project running SQLite database, and the same project deployed on Strapi Cloud with the default PostgreSQL database.

But now I want to point my Strapi project to my external production db hosted on digital ocean.

Let's take a look at how to accomplish this. The steps are similar to how you would do them on a regular project.

But, I wanted to make this walkthrough as a supplementary post to our documentation. Strapi Docs DB Settings

Warning: Before proceeding, make sure you have all your data backed up.

Current Database Settings

We are currently using sqlite database locally and default postgreql on Strapi Cloud.

config/server.js

1const path = require("path");
2
3module.exports = ({ env }) => {
4  const client = env("DATABASE_CLIENT", "sqlite");
5  const connections = {
6    mysql: {
7      connection: {
8        connectionString: env("DATABASE_URL"),
9        host: env("DATABASE_HOST", "localhost"),
10        port: env.int("DATABASE_PORT", 3306),
11        database: env("DATABASE_NAME", "strapi"),
12        user: env("DATABASE_USERNAME", "strapi"),
13        password: env("DATABASE_PASSWORD", "strapi"),
14        ssl: env.bool("DATABASE_SSL", false) && {
15          key: env("DATABASE_SSL_KEY", undefined),
16          cert: env("DATABASE_SSL_CERT", undefined),
17          ca: env("DATABASE_SSL_CA", undefined),
18          capath: env("DATABASE_SSL_CAPATH", undefined),
19          cipher: env("DATABASE_SSL_CIPHER", undefined),
20          rejectUnauthorized: env.bool(
21            "DATABASE_SSL_REJECT_UNAUTHORIZED",
22            true
23          ),
24        },
25      },
26
27      pool: {
28        min: env.int("DATABASE_POOL_MIN", 2),
29        max: env.int("DATABASE_POOL_MAX", 10),
30      },
31    },
32
33    mysql2: {
34      connection: {
35        host: env("DATABASE_HOST", "localhost"),
36        port: env.int("DATABASE_PORT", 3306),
37        database: env("DATABASE_NAME", "strapi"),
38        user: env("DATABASE_USERNAME", "strapi"),
39        password: env("DATABASE_PASSWORD", "strapi"),
40        ssl: env.bool("DATABASE_SSL", false) && {
41          key: env("DATABASE_SSL_KEY", undefined),
42          cert: env("DATABASE_SSL_CERT", undefined),
43          ca: env("DATABASE_SSL_CA", undefined),
44          capath: env("DATABASE_SSL_CAPATH", undefined),
45          cipher: env("DATABASE_SSL_CIPHER", undefined),
46          rejectUnauthorized: env.bool(
47            "DATABASE_SSL_REJECT_UNAUTHORIZED",
48            true
49          ),
50        },
51      },
52
53      pool: {
54        min: env.int("DATABASE_POOL_MIN", 2),
55        max: env.int("DATABASE_POOL_MAX", 10),
56      },
57    },
58
59    postgres: {
60      connection: {
61        connectionString: env("DATABASE_URL"),
62        host: env("DATABASE_HOST", "localhost"),
63        port: env.int("DATABASE_PORT", 5432),
64        database: env("DATABASE_NAME", "strapi"),
65        user: env("DATABASE_USERNAME", "strapi"),
66        password: env("DATABASE_PASSWORD", "strapi"),
67
68        ssl: env.bool("DATABASE_SSL", false) && {
69          key: env("DATABASE_SSL_KEY", undefined),
70          cert: env("DATABASE_SSL_CERT", undefined),
71          ca: env("DATABASE_SSL_CA", undefined),
72          capath: env("DATABASE_SSL_CAPATH", undefined),
73          cipher: env("DATABASE_SSL_CIPHER", undefined),
74          rejectUnauthorized: env.bool(
75            "DATABASE_SSL_REJECT_UNAUTHORIZED",
76            true
77          ),
78        },
79
80        schema: env("DATABASE_SCHEMA", "public"),
81      },
82
83      pool: {
84        min: env.int("DATABASE_POOL_MIN", 2),
85        max: env.int("DATABASE_POOL_MAX", 10),
86      },
87    },
88
89    sqlite: {
90      connection: {
91        filename: path.join(
92          __dirname,
93          "..",
94          env("DATABASE_FILENAME", "data.db")
95        ),
96      },
97      useNullAsDefault: true,
98    },
99  };
100
101  return {
102    connection: {
103      client,
104      ...connections[client],
105      acquireConnectionTimeout: env.int("DATABASE_CONNECTION_TIMEOUT", 60000),
106    },
107  };
108};

The above file is used to configure your server. And most of the work is already done. But first, we must add your database credential on Strapi Cloud to point to our external database and then redeploy our project.

Let's see how this is done.

Adding External Database Credentials

Before saving and pushing changes to github let's log into Strapi Cloud and add our environment variables.

1# Database
2
3DATABASE_CLIENT=postgres
4DATABASE_HOST=your_host
5DATABASE_PORT=your_port
6DATABASE_NAME=your_db_name
7DATABASE_USERNAME=your_username
8DATABASE_PASSWORD=your_password
9DATABASE_SSL=true
10DATABASE_SSL_REJECT_UNAUTHORIZED=false
11DATABASE_SHEMA=public

Note: To ensure a smooth deployment, it is recommended to not change the names of the environment variables.

You can add your variables under Settings -> Variables:

Once you added all your required variables, click the save button.

If you have any changes in the application, you can push them to git and trigger a redeploy; otherwise, you can trigger a redeploy after saving your environment variables.

Since I don't have any changes in code, I will redeploy my project manually.

Once your application is finished building, you should now be using your external database.

Reverting Back To Default Database

If you're using Strapi Cloud project and had previously added environment variables related to an external database, reverting back to the default database can be accomplished quickly.

All you need to do is remove the previously added environment variables from the Strapi Cloud project dashboard, click the save button that I forgot to click, and redeploy. This will revert to the default database.

Remember that any data you had on the external database will no longer be accessible after this action.

Conclusion

Strapi Cloud does support external databases. However, it's only recommended if you have a specific reason to do so. In this post, we've walked through the process of adding an external database to a Strapi Cloud project, along with the necessary configurations and environment variables.

We also covered how to revert to the default database. While using an external database may be a viable option for some users, weighing the caveats and understanding the potential risks involved, such as performance impact, network latency, and security concerns, is essential.

Check out the video that walks you through how to add an external database to Strapi Cloud.