# Databases

Strapi gives you the option to choose the most appropriate database for your project. It currently supports PostgreSQL, MongoDB, SQLite, MySQL and MariaDB. The following documentation covers how to install these databases locally (for development purposes) and on various hosted or cloud server solutions (for staging or production purposes).

TIP

Deploying Strapi itself is covered in the Deployment Guide.

# SQLite Installation

SQLite is the default (Quick Start) and recommended database to quickly create an app locally.

# Install SQLite locally

Simply use one of the following commands.

This will create a new project and launch it in the browser.

TIP

The Quick Start Guide is a complete step-by-step tutorial

# MongoDB Installation

# Install MongoDB locally

# 1. Install MongoDB on your development environment

If you already have MongoDB installed locally and running as a background service, you may skip to Install Strapi locally with MongoDB. (If you have additional questions, please see the official MongoDB documentation. )

Please complete the installation steps appropriate to your operating system.

# 2. Install Strapi locally with MongoDB

Follow these steps to create a Strapi project locally using the MongoDB database.

TIP

MongoDB must already be running in the background.

  1. Create a new Strapi project

Path: ./

  • Use your down arrow key and select Custom (manual settings) and press enter:
? Choose your installation type
  Quickstart (recommended)
❯ Custom (manual settings)
  • Select MongoDB and press enter:
? Choose your installation type Custom (manual settings)
? Choose your main database:
  SQLite
❯ MongoDB
  MySQL
  Postgres
  • Press enter to select the remaining default options. It will look something like this:

? Choose your installation type Custom (manual settings)
? Choose your main database: MongoDB
? Database name: my-project
? Host: 127.0.0.1
? +srv connection: false
? Port (It will be ignored if you enable +srv): 27017
? Username:
? Password:
? Authentication database (Maybe "admin" or blank):
? Enable SSL connection: false

⏳ Testing database connection...
The app has been connected to the database successfully!

🏗  Application generation:
✔ Copy dashboard
✔ Installed dependencies.

👌 Your new application my-project is ready at /Users/david/Desktop/Projects/my-project.

⚡️ Change directory:
$ cd my-project

⚡️ Start application:
$ strapi develop

You have successfully installed Strapi with MongoDB on your local development environment. You are now ready to create your first user.

# Install on Atlas: MongoDB Atlas

Follow these steps to configure a local Strapi project to use a MongoDB Atlas free 512 MB account in production. (Please see MongoDB Atlas Documentation if you have any questions.)

# 1. Log in to your account to create a Project and a Cluster

  • First you need to Create a new Project.
  • Then click Build a Cluster, from the options page:
    • Choose AWS as your Cloud Provider & Region.
    • Select a Region. (Note: some Regions do not have a free tier.)
    • In Cluster Tier, select Shared Sandbox, Tier MO.
    • In Cluster Name, name your cluster.
  • Click the green Create Cluster button. You will get a message that says, "Your cluster is being created..."

# 2. Next, click on the Database Access in the left menu (under Overview):

  • Click the green + ADD NEW USER button:
    • Enter a username.
    • Enter a password.
    • Under User Privileges ensure Read and write to any database is selected. Then click Add User to save.

# 3. Then whitelist your IP address. Click into Network Access, under Security in the left menu:

  • Click the green + ADD IP ADDRESS

    • Click ADD CURRENT IP ADDRESS or manually enter in an IP address to whitelist.
    • Leave a comment to label this IP Address. E.g. Office.
    • Then click the green Confirm button.
    • Delete the 0.0.0.0/0 configuration after testing the connection.

    TIP

    If for any reason you need to test the configuration or other aspect of your connection to the database, you may want to set back the Allow Access from Anywhere. Follow this steps:

    • Click the green + ADD IP ADDRESS
      • Next add 0.0.0.0/0 in the Whitelist Entry. Note: In permanent projects you would configure this with the appropriate IP addresses.
      • Leave a comment to label this IP Address. E.g. Anywhere.
      • Click Confirm. Then wait until the status turns from Pending to Active.

    TIP

    If you are serving you Strapi project from a known IP Address then follow the following steps to allow Network Access.

    • Manually enter in an IP address to whitelist, for your Strapi server.
    • Leave a comment to label this IP Address. E.g. Heroku Server
    • Then click the green Confirm button.

# 4. Retrieve database credentials

MongoDB Atlas automatically exposes the database credentials into a single environment variable accessible by your app. To locate it, follow these steps:

  • Under Atlas in the left-hand, click on Clusters. This should take you to your cluster. Next, click CONNECT and then Connect Your Application.
  • Under 1. Choose your driver version, select DRIVER as Node.js and VERSION as 2.2.12 or later.

    WARNING

    You must use Version: 2.2.12 or later.

  • This should show a Connection String Only similar to this:

mongodb://paulbocuse:<password>@strapi-heroku-shard-00-00-oxxxo.mongodb.net:27017,strapi-heroku-shard-00-01-oxxxo.mongodb.net:27017,strapi-heroku-shard-00-02-oxxxo.mongodb.net:27017/test?ssl=true&replicaSet=Strapi-Heroku-shard-0&authSource=admin&retryWrites=true&w=majority

WARNING

Please note the <password> after your username. In this example, after mongodb://paulbocuse:. You will need to replace the <password> with the password you created earlier for this user in your MongoDB Atlas account.

# 5. Update and replace your existing /database.js config file for the appropriate environment (development | production).

Replace the contents of /database.js with the following and replace < password > with the password of the user of your database you created earlier:

Path: ./config/database.js.

module.exports = ({ env }) => ({
  defaultConnection: 'default',
  connections: {
    default: {
      connector: 'mongoose',
      settings: {
        uri: env('DATABASE_URI'),
      },
      options: {
        ssl: true,
      },
    },
  },
});

Path: .env

DATABASE_URI=mongodb://paulbocuse:<password>@strapidatabase-shard-00-00-fxxx6c.mongodb.net:27017,strapidatabase-shard-00-01-fxxxc.mongodb.net:27017,strapidatabase-shard-00-02-fxxxc.mongodb.net:27017/test?ssl=true&replicaSet=strapidatabase-shard-0&authSource=admin&retryWrites=true&w=majority

NOTE

The above configuration will create a database called strapi, the default database Strapi sets for any MongoDB database. If you would like to name your database something else, add the following key:value pair into your settings: located in your database.js file.

database: 'my-database-name'

WARNING

We recommend replacing sensitive (eg. "URI string" above) information in your database configuration files before uploading your project to a public repository such as GitHub. For more information about using environment variables, please read configurations.

You are now ready use Strapi locally or to deploy your project to an external hosting provider and use MongoDB Atlas as your database server.

← Draft system →