Quickstart: Create a database and connect to it

Learn how to create a Firestore with MongoDB compatibility database and connect to it with the mongosh tool.

Before you begin

  1. In the Google Cloud console, go to the project selector page.

    Go to project selector

  2. Select or create a Google Cloud project.

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Make sure that you have the following role or roles on the project: roles/datastore.owner

    Check for the roles

    1. In the Google Cloud console, go to the IAM page.

      Go to IAM
    2. Select the project.

    3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

    4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

    Grant the roles

    1. In the Google Cloud console, go to the IAM page.

      Go to IAM
    2. Select the project.
    3. Click Grant access.

    4. In the New principals field, enter your user identifier. This is typically the email address for a Google Account.

    5. In the Select a role list, select a role.
    6. To grant additional roles, click Add another role and add each additional role.
    7. Click Save.
  5. Install the mongosh tool

Create a Firestore with MongoDB compatibility database and retrieve the connection string

In the Google Cloud console, create a new Firestore Enterprise edition database. Firestore with MongoDB compatibility requires Firestore Enterprise edition:

  1. In the Google Cloud console, go to the Databases page.

    Go to Databases

  2. Click Create a Firestore Database.
  3. Enter a database ID.
  4. Select Enterprise Edition.
  5. Select a location for your database.

  6. Click Create Database.

    When the database completes initialization, the console opens the Firestore Studio for your database.

  7. In the Connect to Firestore using an external MongoDB tool section, copy the connection string.

    The connection string depends on the UID of the database (system-generated) and the location of database:

    UID.LOCATION.firestore.goog

Create a user for SCRAM authentication

In the Google Cloud console, create a new database user and assign the user Identity and Access Management permissions.

  1. In the Google Cloud console, go to the Databases page.

    Go to Databases

  2. Select the database from the list of databases.
  3. In the navigation menu, click Auth.
  4. Click Add User.
  5. Enter a username.
  6. Select an Identity and Access Management role for the user.
  7. Click create. The database creates a user and shows you the user's generated password. Copy and save this password. You will not be able to retrieve this password later..

Connect using mongosh

Use the connection string, username, and password to connect to your database, run mongosh locally with the following configuration options.

mongosh 'mongodb://USERNAME:PASSWORD@CONNECTION_STRING:443/DATABASE_ID?loadBalanced=true&authMechanism=SCRAM-SHA-256&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:FIRESTORE&tls=true&retryWrites=false'

Replace the following:

  • USERNAME: the name of the database user you created.
  • PASSWORD: the generated password for the database user you created.
  • CONNECTION_STRING: the database connection string.
  • DATABASE_ID: a database ID

Once connected, you can create and read data, for example:

db.pages.insertOne({ message: "Hello World!"})
db.pages.find({})
exit

Clean up

To clean up the resources used on this page, delete the database user and delete the database.

Delete the database user

Delete the database user to remove the user and the assigned Identity and Access Management permissions.

  1. In the Google Cloud console, go to the Databases page.

    Go to Databases

  2. Select the database from the list of databases.
  3. In the navigation menu, click Auth.
  4. Click Actions in the Actions column for the user you want to delete. Click Delete user. A dialog appears.
  5. Confirm deletion and click Delete.
  6. A dialog shows a link to the IAM page. Click the link to delete the permissions assigned to the database user.

  7. Find the row containing the principal whose access you want to revoke. Then, click Edit principal in that row.

    The principal for the database user you created uses the following naming format:

    principal://firestore.googleapis.com/projects/PROJECT_NUMBER/name/databases/DATABASE_ID/userCreds/USER_ID
  8. Click the Delete button for the role that you want to revoke, and then click Save.

Delete the database

Complete the following to delete the database:

  1. In the Google Cloud console, go to the Databases page.

    Go to Databases

  2. Click View more in the Actions column for the database you want to delete. Click Delete. A dialog appears.

  3. In the Delete database? dialog, confirm deletion by typing the database ID in the text field. Click Delete. The console informs you of operation success or failure.

    If the operation fails, view the database details and verify that delete protection is disabled. To disable delete protection, see Update the delete protection setting.

What's next