Criar um MongoClient
Nesta página
Visão geral
Para se conectar a um MongoDB deployment, você precisa de duas coisas:
Um URI de conexão, também conhecido como connection string, que informa ao PyMongo a qual deployment do MongoDB se conectar.
Um objeto MongoClient , que cria a conexão com a implantação do MongoDB e permite que você execute operações nele.
Você também pode usar qualquer um desses componentes para personalizar a maneira como o PyMongo se comporta enquanto estiver conectado ao MongoDB.
Este guia mostra como criar uma string de conexão e usar um objeto MongoClient para se conectar ao MongoDB.
URI de conexão
Uma connection string padrão inclui os seguintes componentes:
Componente | Descrição |
|---|---|
| Obrigatório. Um prefixo que identifica isso como uma string no formato de conexão padrão. |
| Opcional. Credenciais de autenticação. Se você incluir estes, o cliente autenticará o usuário no banco de banco de dados especificado no |
| Obrigatório. O host e o número da porta opcional em que o MongoDB está sendo executado. Se você não incluir o número da porta, o driver usará a porta padrão, |
| Opcional. O authentication database de autenticação a ser usado se a connection string incluir as credenciais de autenticação |
| Opcional. Uma string de consulta que especifica opções específicas de conexão como |
Para obter mais informações sobre a criação de uma connection string, consulte Connection strings na documentação do MongoDB Server .
Cliente Mongo
Para criar uma conexão com o MongoDB, passe um URI de conexão como uma string para o construtor MongoClient . No exemplo a seguir, o driver usa um URI de conexão de exemplo para se conectar a uma instância MongoDB na porta 27017 de localhost:
from pymongo import MongoClient uri = "mongodb://localhost:27017/" client = MongoClient(uri)
A tabela seguinte descreve os parâmetros posicionais que o construtor do MongoClient() aceita. Todos os parâmetros são opcionais.
Parâmetro | Descrição | ||
|---|---|---|---|
| O nome do host, o endereço IP ou o caminho do soquete do domínio Unix da implantação do MongoDB . Se seu aplicação se conectar a um conjunto de réplicas ou cluster fragmentado, você poderá especificar vários nomes de host ou endereços IP em uma lista do Python. Se você passar um endereço IPv6 literal, deverá colocar o endereço entre colchetes ( O PyMongo não suporta endereços DNS multiprovedores e round-robin. Tipo de dados: | ||
| O número da porta em que o MongoDB Server está sendo executado. Você pode incluir o número da porta no argumento Tipo de dados: | ||
| A classe padrão que o cliente usa para decodificar documentos BSON retornados por queries. Este parâmetro aceita os seguintes tipos:
Tipo de dados: | ||
| Se este parâmetro for Para obter mais informações sobre valores cientes e ingênuos Tipo de dados: | ||
| Se este parâmetro for Se seu aplicação estiver sendo executado em um ambiente de função como serviço (FaaS), o valor padrão será Tipo de dados: | ||
| Uma instância da classe Tipo de dados: TypeRegistry |
Você também pode passar argumentos de palavra-chave para o construtor do MongoClient() para especificar parâmetros opcionais. Para obter uma lista completa de argumentos de palavra-chave, consulte a classe MongoClient na documentação da API.
Execução simultânea
As seções a seguir descrevem o suporte do PyMongo para mecanismos de execução simultâneos.
Multithreading
O PyMongo é thread-safe e oferece pool de conexões integrado para aplicativos thread-safe. Como cada objeto MongoClient representa um pool de conexões com o banco de dados, a maioria dos aplicativos exige somente uma única instância de MongoClient, mesmo em várias solicitações.
Várias bifurcações
O PyMongo suporta chamar o método fork() para criar um novo processo. No entanto, se você bifurcar um processo, deverá criar uma nova instância MongoClient no processo filho.
Importante
Não passe um MongoClient para um processo filho
Se você utilizar o método fork() para criar um novo processo, não passe uma instância da classe MongoClient do processo pai para o processo filho. Isto cria uma alta probabilidade de impasse entre as instâncias do MongoClient no processo filho. O PyMongo tenta emitir um aviso se esse impasse puder ocorrer.
Para obter mais informações sobre o deadlock em processos bifurcados, consulte Forking um processo causa um deadlock.
Multiprocessamento
O PyMongo suporta o módulo Python multiprocessing. No entanto, em sistemas Unix, o módulo de multiprocessamento gera processos usando o método fork(). Isso acarreta os mesmos riscos descritos em Multiple Forks
Para usar o multiprocessamento com o PyMongo, escreva código semelhante ao exemplo a seguir:
# Each process creates its own instance of MongoClient. def func(): db = pymongo.MongoClient().mydb # Do something with db. proc = multiprocessing.Process(target=func) proc.start()
Importante
Não copie uma instância da classe MongoClient do processo pai para um processo filho.
Dicas de tipo
Se seu aplicação usar o Python 3.5 ou posterior, você poderá adicionar dicas de tipo, conforme descrito em PEP 484, ao seu código. As dicas de tipo denotam os tipos de dados de variáveis, parâmetros e valores de retorno de função, e a estrutura de documentos. Alguns IDEs podem usar dicas de tipo para verificar erros de tipo seu código e sugerir opções apropriadas para a conclusão do código.
Para usar dicas de tipo no seu aplicação PyMongo, você deve adicionar uma anotação de tipo ao seu objeto MongoClient, conforme mostrado no exemplo a seguir:
client: MongoClient = MongoClient()
Para obter informações de tipo mais precisas, você pode incluir o tipo de documento genérico Dict[str, Any] em sua anotação de tipo. Este tipo de dados corresponde a todos os documentos no MongoDB. O exemplo a seguir mostra como incluir este tipo de dados em sua anotação de tipo:
from typing import Any, Dict client: MongoClient[Dict[str, Any]] = MongoClient()
Se todos os documentos com os quais você está trabalhando corresponderem a um único tipo personalizado, você poderá especificar o tipo personalizado como uma dica de tipo para seu objeto MongoClient. Isso fornece informações de tipo mais precisas do que o tipo Dict[str, Any] genérico.
O exemplo a seguir mostra como especificar o tipo Movie como dica de tipo para um objeto MongoClient:
from typing import TypedDict class Movie(TypedDict): name: str year: int client: MongoClient[Movie] = MongoClient()
Solução de problemas
Erro de configuração do MongoClient
Fornecer nomes de argumentos de palavras-chave inválidos faz com que o driver gere esse erro.
Verifique se os argumentos de palavra-chave especificados existem e estão escritos corretamente.
Bifurcar um processo causa um impasse
Uma instância do MongoClient gera vários threads para executar tarefas em segundo plano, como monitorar servidores conectados. Essas threads compartilham um estado protegido por instâncias da threading.Lock classe , que não são seguras para bifurcações . O PyMongo está sujeito às mesmas limitações que qualquer outro código multithread que use a classe threading.Lock ou quaisquer mutexes.
Uma dessas limitações é que as travas se tornam inúteis após chamar o método fork() . Quando o fork() é executado, o driver copia todos os bloqueios do processo pai para o processo filho no mesmo estado em que estavam no pai. Se estiverem bloqueados no processo pai, também estarão bloqueados no processo filho. O processo filho criado por fork() tem apenas um thread, portanto, quaisquer bloqueios criados por outros threads no processo pai nunca são liberados no processo filho. Da próxima vez que o processo filho tentar adquirir uma dessas travas, ocorrerá um impasse.
A partir da versão 4.3 do PyMongo, depois de chamar o método os.fork() , o driver usa o método os.register_at_fork() para redefinir suas travas e outros estados compartilhados no processo filho. Embora isso reduza a probabilidade de um impasse, o PyMongo depende de bibliotecas que não são seguras para fork em aplicativos de várias threads, incluindo OpenSSL e getaddrinfo(3). Portanto, um impasse ainda pode ocorrer.
A página de manual do Linux para fork(2) também impõe a seguinte restrição:
Após um
fork()em um programa de várias threads, a criança pode chamar com segurança somente funções seguras com sinal assíncrono (consulte segurança de sinal(7)) até o momento em que chama execve(2).
Como o PyMongo depende de funções que não são seguras contra sinais assíncronos, ele pode causar impasses ou falhas ao ser executado em um processo filho.
Dica
Para obter um exemplo de um impasse em um processo filho, consulte PYTHON-3406 em Jira.
Para obter mais informações sobre os problemas causados por bloqueios do Python em contextos multithread com fork(), consulte Problema 6721 no Rastreador de problemas do Python.
Anotações do tipo de cliente
Se você não adicionar uma anotação de tipo para seu objeto MongoClient, seu verificador de tipo poderá mostrar um erro semelhante ao seguinte:
from pymongo import MongoClient client = MongoClient() # error: Need type annotation for "client"
A solução é anotar o objeto MongoClient como client: MongoClient ou client: MongoClient[Dict[str, Any]].
Tipo incompatível
Se você especificar MongoClient como uma dica de tipo, mas não incluir tipos de dados para o documento, as chaves e os valores, seu verificador de tipo poderá mostrar um erro semelhante ao seguinte:
error: Dict entry 0 has incompatible type "str": "int"; expected "Mapping[str, Any]": "int"
A solução é adicionar a seguinte dica de tipo ao seu objeto MongoClient :
``client: MongoClient[Dict[str, Any]]``
Documentação da API
Para saber mais sobre como criar um objeto MongoClient no PyMongo, consulte a seguinte documentação da API: