Menu Docs
Página inicial do Docs
/ / /
Laravel MongoDB
/ /

Guia de conexão

Nesta página

  • Visão geral
  • URI de conexão
  • Partes de um URI de conexão
  • Configuração da conexão do banco de dados Laravel
  • Exemplo de conexão
  • Outras maneiras de se conectar ao MongoDB
  • Conecte-se a um servidor MongoDB em sua máquina local
  • Conectar a um conjunto de réplicas

Neste guia, você aprenderá como conectar seu aplicativo Laravel a uma instância do MongoDB ou a um sistema de conjunto de réplicas usando o Laravel MongoDB.

Este guia inclui as seguintes seções:

  • URI de conexão, que explica os URIs de conexão e suas partes constituintes

  • Configuração da conexão do banco de dados Laravel, que explica como configurar sua conexão do MongoDB database para seu aplicativo Laravel.

  • Exemplo de conexão, que fornece exemplos que mostram como se conectar ao MongoDB usando uma connection string do Atlas.

  • Outras Maneiras de Conectar ao MongoDB descreve maneiras de se conectar a implementações do MongoDB que não estão hospedadas no Atlas.

Um URI de conexão, também conhecido como string de conexão, especifica como a integração do Laravel se conecta ao MongoDB e como se comportar enquanto estiver conectado.

A figura a seguir explica cada parte de um URI de conexão de amostra:

Partes de um URI de conexão

Neste URI de conexão, mongodb+srv é o protocolo, que usa o formato de conexão da lista de sementes do DNS para maior flexibilidade em sua implantação e a capacidade de alterar os servidores em rotação sem reconfigurar os clientes.

Se a máquina que hospeda sua implementação do MongoDB não for compatível com esse recurso, use o protocolo para o formato de string de caracteres de conexão padrão .

Se você usar uma autenticação baseada em senha, a parte da connection string após o protocolo conterá seu nome de usuário e senha. Substitua o espaço reservado para user pelo seu nome de usuário e pass pela sua senha. Se você usar um mecanismo de autenticação que não requer um nome de usuário e senha, omita esta parte do URI de conexão.

A parte da connection string após as credenciais especifica o nome de host ou endereço IP e porta da instância do MongoDB. O exemplo anterior utiliza sample.host como o nome do host e 27017 como a porta. Substitua esses valores para apontar para a sua instância MongoDB.

A última parte da connection string especifica as opções de conexão e autenticação. No exemplo, definimos as seguintes opções e valores de conexão:

  • maxPoolSize=20

  • w=majority

Para saber mais sobre as opções de conexão, consulte Opções de conexão .

A integração do Laravel permite configurar sua conexão do banco de dados de dados MongoDB no arquivo de aplicação config/database.php Laravel. Você pode especificar os seguintes detalhes da conexão neste arquivo:

  • default, que especifica a conexão do banco de dados a ser usada quando não for especificado

  • connections, que contém informações de conexão do banco de dados para acessar um ou mais bancos de dados do seu aplicativo

Você pode usar o seguinte código no arquivo de configuração para definir a conexão padrão para uma entrada mongodb correspondente na array connections :

'default' => 'mongodb',

Para uma conexão do MongoDB database , você pode especificar os seguintes detalhes:

Contexto
Descrição
driver
Especifica o driver do banco de dados a ser usado para a conexão.
dsn
O nome da fonte de dados (DSN) que especifica o URI de conexão MongoDB.
host
Specifies the network address and port of one or more MongoDB nodes in a deployment. You can use this setting instead of the dsn setting.
To specify a single host, pass the hostname and port as a string as shown in the following example:
'host' => 'myhost.example.com:27017',
To specify multiple hosts, pass them in an array as shown in the following example::
'host' => ['node1.example.com:27017', 'node2.example.com:27017', 'node3.example.com:27017'],
This option does not accept hosts that use the DNS seedlist connection format.
database
Especifica o nome do banco de MongoDB database para ler e gravar.
username
Especifica a credencial de nome de usuário do banco de dados para autenticar com o MongoDB.
password
Especifica a credencial de senha do usuário do banco de dados para autenticar com MongoDB.
options
Especifica as opções de conexão a serem passadas ao MongoDB que determinam o comportamento da conexão. Para saber mais sobre as opções de conexão, consulte Opções de conexão e autenticação.
driver_options
Especifica opções específicas a serem passadas para a biblioteca PHP do MongoDB que determinam o comportamento do driver para essa conexão. Para saber mais sobre as opções de driver, consulte Opções de conexão de driver.

Observação

Você pode especificar as seguintes configurações na configuração do dsn como parâmetros em sua connection string MongoDB em vez de itens de array:

  • host

  • username

  • password

  • options e driver_options, especificados pelo nome da opção

O exemplo a seguir mostra como você pode especificar os detalhes da conexão do MongoDB no item de array connections :

Exemplo de configuração de conexão do MongoDB config/database.php
'connections' => [
'mongodb' => [
'driver' => 'mongodb',
'dsn' => 'mongodb+srv//myUser:myPass123@sample.host:27017/',
'database' => 'sample_mflix',
'options' => [
'maxPoolSize' => 20,
'w' => 'majority',
],
'driver_options' => [
'serverApi' => 1,
],
],
// ...
],

As seções a seguir fornecem maneiras comuns de especificar conexões MongoDB.

Esta seção mostra como configurar o DSN do seu aplicativo Laravel usando uma connection string do MongoDB Atlas.

Para adicionar seu DSN do MongoDB ao seu aplicativo Laravel, faça as seguintes alterações:

  • Adicione o DSN como uma variável de ambiente no arquivo de configuração de ambiente .env do seu projeto. Defina o valor da variável para sua connection string do Atlas.

  • Adicione uma entrada de conexão para sua conexão MongoDB na array connections do seu arquivo de configuração config/database.php . Defina o valor dsn da entrada de conexão para fazer referência à variável de ambiente que contém seu DSN.

Os seguintes exemplos mostram como especificar o "mongodb+srv://myUser:myPass123@mongodb0.example.com/" como a connection string nos arquivos de configuração relevantes:

Amostra de arquivo .env configuração do ambiente
DB_URI="mongodb+srv://myUser:myPass123@mongodb0.example.com/"
Exemplo de entrada de conexão config/database.php
'connections' => [
'mongodb' => [
'dsn' => env('DB_URI'), // uses the value of the DB_URI environment variable
'driver' => 'mongodb',
'database' => 'sample_mflix',
// ...
],
// ...
]

Dica

Para recuperar sua Atlas connection do string, siga a etapa Criar uma string connection do tutorial de Início rápido.

As seções seguintes mostram como conectar a uma única instância do servidor MongoDB ou a um conjunto de réplica não hospedado no MongoDB Atlas.

Esta seção mostra um exemplo de connection string que você pode usar ao executar um aplicativo Laravel e um servidor MongoDB na mesma máquina, como seu ambiente de desenvolvimento local.

Para conectar seu aplicativo a uma instância do MongoDB hospedada na mesma máquina, você deve concluir as seguintes tarefas:

  • Baixe, instale e execute o servidor MongoDB.

  • Obtenha o endereço IP e a porta na qual seu servidor MongoDB está sendo executado. Se você usar as configurações padrão de uma instalação local do servidor MongoDB, o endereço IP será 127.0.0.1 e a porta será 27017.

  • Configure sua conexão config/database.php para fazer referência à variável de ambiente DB_URI para o valor do dsn, conforme mostrado na seção Exemplo de conexão .

O exemplo a seguir mostra uma connection string de exemplo que você pode adicionar ao arquivo .env se o seu aplicativo se conectar a um servidor MongoDB em execução no endereço IP e porta padrão:

Amostra de arquivo .env configuração de ambiente para se conectar a um servidor MongoDB local.
DB_URI="mongodb://127.0.0.1:27017/";

Para saber como baixar e instalar o servidor MongoDB , consulte Instalar MongoDB Community Edition no manual do servidor MongoDB.

Um sistema do conjunto de réplicas MongoDB é um grupo de instâncias conectadas, ou nós, onde os nós armazenam o mesmo conjunto de dados. Esta configuração de instâncias fornece redundância de dados e alta disponibilidade de dados.

Para conectar a um sistema do conjunto de réplicas, especifique o nome do host e o número da porta de cada nó, separados por vírgulas, e o nome do conjunto de réplicas como o valor do parâmetro replicaSet na connection string.

Este exemplo, que mostra a connection string que você pode adicionar ao arquivo .env do seu aplicativo Laravel para se conectar a um conjunto de réplicas, usa os seguintes valores de amostra:

  • host1, host2 e host3 como os nomes de host dos nós MongoDB

  • 27017 como a porta na qual o MongoDB é executado nesses hosts

  • myRS como o nome configurado do conjunto de réplicas

  • myUser e myPass123 como as credenciais de um utilizador de banco de dados

DB_URI="mongodb://myUser:myPass123@host1:27017,host2:27017,host3:27017/?replicaSet=myRS"

Ao se conectar a um conjunto de réplicas, a biblioteca que a integração do Laravel usa para gerenciar conexões com o MongoDB executa as seguintes ações, a menos que especificado de outra forma:

  • Descobre todos os membros do conjunto de réplicas quando recebe o endereço de qualquer membro.

  • Envia operações para o membro apropriado, como instruções para escrever no nó primário . Para saber mais sobre o conjunto de réplicas primário, consulte Conjunto de réplicas primário no manual do servidor MongoDB.

Dica

É necessário especificar apenas um host para se conectar a um conjunto de réplicas. No entanto, para garantir a conectividade quando o host selecionado não estiver disponível, forneça a lista completa de hosts.

Para saber mais sobre como configurar um conjunto de réplicas MongoDB , consulte Implementar um conjunto de réplicas no manual do servidor MongoDB.

Para forçar a execução de operações em um nó específico em um conjunto de réplicas do MongoDB, especifique as informações de conexão do nó na connection string e o parâmetro directConnection com um valor true .

As conexões diretas incluem as seguintes limitações:

  • As connection strings de formato de conexão da lista de sementes de DNS não podem ser usadas.

  • As operações de gravação falham quando o host especificado não é o primary.

  • Quando o host não for o primary, você deverá especificar a preferência de leitura secondary nas opções de conexão. Para saber mais sobre essa limitação, consulte a entrada de preferência de leitura secundária no manual do servidor MongoDB.

O exemplo abaixo mostra a connection string que você pode adicionar ao arquivo .env do seu aplicativo Laravel para estabelecer uma conexão direta com um nó secundário em um conjunto de réplicas do MongoDB. O exemplo utiliza os seguintes valores de amostra:

  • host2 como o nome do host do nó secundário

  • 27017 como a porta na qual o nó do MongoDB escuta

Amostra de arquivo .env configuração do ambiente para habilitar uma conexão direta
DB_URI="mongodb://host2:27017/?directConnection=true&readPreference=secondary"

Voltar

Conexões