Discuss with expertTry it for free
© 2026 Direct Cursus Technology L.L.C.

Connecting to a Yandex StoreDoc cluster from applications

Written by
Updated at July 28, 2026
View in Markdown

You can connect to a Yandex StoreDoc cluster using command line tools, graphical IDEs, or Docker containers. To learn how to connect from the code of your application, see Code examples.

In the following examples, we assume that the root.crt SSL certificate is located in one of these directories:

  • ~/.mongodb/ for Ubuntu
  • $HOME\.mongodb for Windows

After you successfully connect to the cluster and run a test query, you will see the name of the database you connected to.

Warning

Queries with the writeConcern: 1 setting may lead to lagging data on secondary replicas. This increases the risk of write timeouts and data loss if the master host fails. Therefore, the SLA and high availability guarantees do not apply to such clusters. For more information on how writeConcern impacts high availability, see here.

Command line tools

To see code examples with the host FQDN filled in, open the cluster page in the management console and click Connect.

The setup method depends on whether sharding is enabled in the cluster:

Linux (Bash)

Before connecting, install MongoDB Shell.

For a non-sharded cluster:

mongosh --norc \
        --tls \
        --tlsCAFile ~/.mongodb/root.crt \
        --host '<Yandex_StoreDoc_host_1_FQDN>:27018,...,<Yandex_StoreDoc_host_N_FQDN>:27018' \
        --username <DB_user_name> \
        --password <DB_user_password> \
        <DB_name>

For a sharded cluster:

mongosh --norc \
        --tls \
        --tlsCAFile ~/.mongodb/root.crt \
        --host '<MONGOINFRA_or_MONGOS_host_1_FQDN>:27017,...,<MONGOINFRA_or_MONGOS_host_N_FQDN>:27017' \
        --username <DB_user_name> \
        --password <DB_user_password> \
        <DB_name>

To learn how to get a host FQDN, see this guide.

Once connected, run the db command.

For a non-sharded cluster:

mongosh --norc \
        --host '<Yandex_StoreDoc_host_1_FQDN>:27018,...,<Yandex_StoreDoc_host_N_FQDN>:27018' \
        --username <DB_user_name> \
        --password <DB_user_password> \
        <DB_name>

For a sharded cluster:

mongosh --norc \
        --host '<MONGOINFRA_or_MONGOS_host_1_FQDN>:27017,...,<MONGOINFRA_or_MONGOS_host_N_FQDN>:27017' \
        --username <DB_user_name> \
        --password <DB_user_password> \
        <DB_name>

To learn how to get a host FQDN, see this guide.

Once connected, run the db command.

mongosh "mongodb+srv://<DB_user_name>:<DB_user_password>\
@<cluster_ID>.mdb.yandexcloud.net/<DB_name>"

You can get the cluster ID with the list of clusters in the folder.

Once connected, run the db command.

You can add connection parameters to the command, if required, for example:

  • tls: Enables TLS encryption for the connection (true or false). Encryption is enabled by default.
  • tlsCAFile: Path to the .pem file with root certificates from the CA.
  • readPreference: Hosts to read from:
    • primary: Only the primary replica (master).
    • primaryPreferred: Master or secondary replicas if the master is unavailable.
    • secondary: Only secondary replicas.
    • secondaryPreferred: Secondary replicas or the master if there are no secondary replicas.
    • nearest: Least lagging host.
  • authSource: Name of the database storing the user credentials. By default, it is the same as <DB_name>.
  • appName: App name to display in logs.

For more information about available connection parameters, see this official guide.

The parameter string begins with the ? character, and & is the separator.

Example of a command with connection properties:

mongosh "mongodb+srv://user********:qwe********@c9qng7jhsgtg********.mdb.yandexcloud.net\
/db********?authSource=admin&appName=debug"

Windows (PowerShell)

Before connecting, install MongoDB Shell.

For a non-sharded cluster:

mongosh.exe --norc `
            --host '<Yandex_StoreDoc_host_1_FQDN>:27018,...,<Yandex_StoreDoc_host_N_FQDN>:27018' `
            --tls `
            --tlsCAFile $HOME\.mongodb\root.crt `
            --username <DB_user_name> `
            --password <DB_user_password> `
            <DB_name>

For a sharded cluster:

mongosh.exe --norc `
            --host '<MONGOINFRA_or_MONGOS_host_1_FQDN>:27017,...,<MONGOINFRA_or_MONGOS_host_N_FQDN>:27017' `
            --tls `
            --tlsCAFile $HOME\.mongodb\root.crt `
            --username <DB_user_name> `
            --password <DB_user_password> `
            <DB_name>

To learn how to get a host FQDN, see this guide.

Once connected, run the db command.

For a non-sharded cluster:

mongosh.exe --norc `
            --host '<Yandex_StoreDoc_host_1_FQDN>:27018,...,<Yandex_StoreDoc_host_N_FQDN>:27018' `
            --username <DB_user_name> `
            --password <DB_user_password> `
            <DB_name>

For a sharded cluster:

mongosh.exe --norc `
            --host '<MONGOINFRA_or_MONGOS_host_1_FQDN>:27017,...,<MONGOINFRA_or_MONGOS_host_N_FQDN>:27017' `
            --username <DB_user_name> `
            --password <DB_user_password> `
            <DB_name>

To learn how to get a host FQDN, see this guide.

Once connected, run the db command.

mongosh.exe "mongodb+srv://<DB_user_name>:<DB_user_password>`
@<cluster_ID>.mdb.yandexcloud.net/<DB_name>"

You can get the cluster ID with the list of clusters in the folder.

Once connected, run the db command.

You can add connection parameters to the command, if required, for example:

  • tls: Enables TLS encryption for the connection (true or false). Encryption is enabled by default.
  • tlsCAFile: Path to the .pem file with root certificates from the CA.
  • readPreference: Hosts to read from:
    • primary: Only the primary replica (master).
    • primaryPreferred: Master or secondary replicas if the master is unavailable.
    • secondary: Only secondary replicas.
    • secondaryPreferred: Secondary replicas or the master if there are no secondary replicas.
    • nearest: Least lagging host.
  • authSource: Name of the database storing the user credentials. By default, it is the same as <DB_name>.
  • appName: App name to display in logs.

For more information about available connection parameters, see this official guide.

The parameter string begins with the ? character, and & is the separator.

Example of a command with connection properties:

mongosh.exe "mongodb+srv://user********:qwe********@c9qng7jhsgtg********.mdb.yandexcloud.net`
/db********?authSource=admin&appName=debug"

Connecting with IAM authentication

You can connect to a Yandex StoreDoc cluster using IAM authentication. This authentication option is supported for Yandex accounts, federated accounts, and local accounts.

The connection is established via MongoDB Shell. For information on how to install MongoDB Shell, see this guide.

Before you proceed with connection, configure the security groups and enable public access to the cluster hosts if connecting over the internet.

To connect to a cluster using IAM authentication:

  1. Set up authentication:

    1. Open the folder dashboard.

    2. Navigate to Yandex StoreDoc.

    3. Select the cluster.

    4. Assign the Yandex Cloud account the managed-mongodb.clusters.connector role for the cluster:

      1. Select the Access bindings tab.

      2. Click Assign roles in the top-right corner of the page.

      3. In the Who to grant access to field, select the account.

        To find the account you need, enter its associated email address.

      4. Click Add role and select the managed-mongodb.clusters.connector role.

      5. Click Save.

    5. Create a user named Yandex StoreDoc:

      1. Select  Users.

      2. Click Create user in the top-right corner of the page.

      3. Choose the IAM authorization method.

      4. Select the Yandex Cloud account with the managed-mongodb.clusters.connector role.

      5. Select the databases and configure roles for them:

        1. Click Add database and select the database.

        2. Assign roles for the selected database.

          To assign a role, click and select the role you need.

      6. Click Create.

  2. Get an IAM token and place it in the IAM_TOKEN environment variable:

    • Guide for a Yandex account.
    • Guide for a federated account.
    • Guide for a local account.

  3. Get an SSL certificate.

  4. Connect to the cluster by running this command:

    For a non-sharded cluster:

    mongosh --norc \
        --tls \
        --tlsCAFile ~/.mongodb/root.crt \
        --host '<MONGOINFRA_or_MONGOS_host_1_FQDN>:27018,...,<MONGOINFRA_or_MONGOS_host_N_FQDN>:27018' \
        --username "<DB_user_name>" \
        --password "$IAM_TOKEN" \
        --authenticationDatabase '$external' \
        --authenticationMechanism PLAIN \
        <DB_name>

    For a sharded cluster:

    mongosh --norc \
        --tls \
        --tlsCAFile ~/.mongodb/root.crt \
        --host '<MONGOINFRA_or_MONGOS_host_1_FQDN>:27017,...,<MONGOINFRA_or_MONGOS_host_N_FQDN>:27017' \
        --username "<DB_user_name>" \
        --password "$IAM_TOKEN" \
        --authenticationDatabase '$external' \
        --authenticationMechanism PLAIN \
        <DB_name>

    Where --username is the database user name, which matches the Yandex Cloud account email address.

    To learn how to get a host FQDN, see this guide.

Connecting from graphical IDEs

Connections were tested in the following environment:

  • MacOS Big Sur 11.3
  • JetBrains DataGrip: 2021.1
  • DBeaver Enterprise: 21.0

From graphical IDEs, you can only connect to public cluster hosts using an SSL certificate.

To avoid connection errors, save the certificate to a local folder that does not require administrator rights to access.

DataGrip

  1. Create a data source:
    1. Select File → New → Data Source → MongoDB.
    2. On the General tab:

      1. Configure the connection as follows:

        • User, Password: Database user name and password.

        • URL: Connection string.

          For a non-sharded cluster:

          mongodb://<Yandex_StoreDoc_host_1_FQDN>:27018,..,<Yandex_StoreDoc_host_N_FQDN>:27018/<DB_name>

          For a sharded cluster:

          mongodb://<MONGOINFRA_or_MONGOS_host_1_FQDN>:27017,...<MONGOINFRA_or_MONGOS_host_N_FQDN>:27017/<DB_name>

          To learn how to get a host FQDN, see this guide.

      2. Click Download to download the connection driver.

    3. On the SSH/SSL tab:
      1. Enable Use SSL.
      2. In the CA file field, specify the path to the SSL certificate for your connection.
  2. Click Test Connection. If the connection is successful, you will see the connection status and information about the DBMS and driver.
  3. Click OK to save the data source.

DBeaver

Connections to Yandex StoreDoc clusters are only available in DBeaver commercial editions.

To connect to your cluster:

  1. Create a new database connection:
    1. In the Database menu, select New connection.
    2. Select MongoDB from the database list.
    3. Click Next.
    4. On the Main tab, specify the connection settings:

      1. Under Address, change Type to URL and specify the connection string.

        For a non-sharded cluster:

        mongodb://<Yandex_StoreDoc_host_1_FQDN>:27018,..,<Yandex_StoreDoc_host_N_FQDN>:27018/<DB_name>

        For a sharded cluster:

        mongodb://<MONGOINFRA_or_MONGOS_host_1_FQDN>:27017,...<MONGOINFRA_or_MONGOS_host_N_FQDN>:27017/<DB_name>

        To learn how to get a host FQDN, see this guide.

      2. In the Device list, select the SCRAM-SHA-256 password encryption type for the connection.

      3. Under Authentication, specify the database user name and password.

    5. On the SSL tab:
      1. Enable Use SSL.
      2. In the Root certificate field, specify the path to your saved SSL certificate file.
      3. Under Settings, check Skip hostname validation.
  2. Click Test connection .... If the connection is successful, you will see the connection status, DBMS information, and driver details.
  3. Click Ready to save the database connection settings.

Before you connect from a Docker container

To connect to a Yandex StoreDoc cluster from a Docker container over SSL, add the following lines to your Dockerfile:

RUN apt-get update && \
    apt-get install wget --yes && \
    mkdir --parents ~/.mongodb && \
    wget "https://storage.yandexcloud.net/cloud-certs/CA.pem" \
         --output-document ~/.mongodb/root.crt && \
    chmod 0644 ~/.mongodb/root.crt

To connect without SSL, no additional Dockerfile configuration is required.

After starting the Docker container, access it and install mongosh, which you will need to connect to the cluster.

Previous
Pre-configuration
Next
Overview