Guia de conexão
Nesta página
Visão geral
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.
URI de conexão
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.
Partes de um URI de conexão
A figura a seguir explica cada parte de um URI de conexão de amostra:
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=20w=majority
Para saber mais sobre as opções de conexão, consulte Opções de conexão .
Configuração da conexão do banco de dados Laravel
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 especificadoconnections, 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: To specify multiple hosts, pass them in an array as shown in the
following example:: ObservaçãoEsta opção não aceita hosts que usam o formato de conexão de lista de valores iniciais DNS. | ||
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:
hostusernamepasswordoptionsedriver_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 :
'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.
Exemplo de conexão
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
.envdo 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
connectionsdo seu arquivo de configuraçãoconfig/database.php. Defina o valordsnda 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:
DB_URI="mongodb+srv://myUser:myPass123@mongodb0.example.com/"
'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.
Outras maneiras de se conectar ao MongoDB
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.
Conecte-se a um servidor MongoDB em sua máquina local
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.1e a porta será27017.Configure sua conexão
config/database.phppara fazer referência à variável de ambienteDB_URIpara o valor dodsn, 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:
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.
Conectar a um conjunto de réplicas
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,host2ehost3como os nomes de host dos nós MongoDB27017como a porta na qual o MongoDB é executado nesses hostsmyRScomo o nome configurado do conjunto de réplicasmyUseremyPass123como 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.
Conexão direta
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
secondarynas 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:
host2como o nome do host do nó secundário27017como a porta na qual o nó do MongoDB escuta
DB_URI="mongodb://host2:27017/?directConnection=true&readPreference=secondary"