Gitpod uses a relational database management system to store structural data. Gitpod supports MySQL. The database is a central component in Gitpod where all metadata about users and workspaces as well as settings of the Gitpod instance (such as auth providers) are stored. That makes the database a critical component. In case of a database outage, you will not be able to log in, use the Gitpod dashboard, or start workspaces.

In this reference architecture, we use managed MYSQL databases provided by cloud providers.

Gitpod requires your database instance to have a database named gitpod in it.

Cloud provider specific instructions
  • GCP
  • AWS
  • Azure

As a relational database, we create a Google Cloud SQL instance with MySQL 5.7. Use the following commands to create the database instance:

language icon language: 
gcloud sql instances create "${MYSQL_INSTANCE_NAME}" \
    --database-version=MYSQL_5_7 \
    --storage-size=20 \
    --storage-auto-increase \
    --tier=db-n1-standard-2 \
    --region="${REGION}" \
    --replica-type=FAILOVER \

gcloud sql instances patch "${MYSQL_INSTANCE_NAME}" --database-flags \

After that, we create the database named gitpod as well as a dedicated Gitpod database user with a random password.

language icon language: 
gcloud sql databases create gitpod --instance="${MYSQL_INSTANCE_NAME}"

MYSQL_GITPOD_PASSWORD=$(openssl rand -base64 20)
gcloud sql users create "${MYSQL_GITPOD_USERNAME}" \
    --instance="${MYSQL_INSTANCE_NAME}" \

Finally, you need to create a service account that has the roles/cloudsql.client role:

language icon language: 
gcloud iam service-accounts create "${MYSQL_SA}" --display-name "${MYSQL_SA}"
gcloud projects add-iam-policy-binding "${PROJECT_NAME}" \
    --member serviceAccount:"${MYSQL_SA_EMAIL}" --role="roles/cloudsql.client"

Save the service account key to the file ./mysql-credentials.json:

language icon language: 
gcloud iam service-accounts keys create --iam-account "${MYSQL_SA_EMAIL}" \

Was this helpful?