Gatilhos de banco de dados
Nesta página
Gatilhos de banco de dados (triggers) permitem que você execute a lógica do lado do servidor sempre que ocorre uma alteração no banco de dados em um Cluster MongoDB Atlas vinculado. Você pode configurar triggers em collections individuais, bancos de dados inteiros e em todo um cluster.
Ao contrário dos gatilhos de dados SQL, que são executados no servidor de banco de dados de dados, os gatilhos de banco de dados de dados Atlas são executados em uma camada de computação sem servidor que é dimensionada independentemente do servidor de banco de dados de dados. Os acionadores ligam automaticamente para o Atlas Functions e podem encaminhar eventos para manipuladores externos através do Amazon Web Services EventBridge.
Use gatilhos de banco de dados para implementar interações de dados orientadas por eventos. Por exemplo, você pode atualizar automaticamente as informações em um documento quando um documento relacionado é alterado ou enviar uma solicitação para um serviço externo sempre que um novo documento é inserido.
Os gatilhos de banco de dados usam osfluxos de alteração do MongoDB para observar alterações em tempo real em uma coleção. Um change stream é uma série de eventos de banco de dados de dados em que cada um descreve uma operação em um documento na collection. A sua aplicação abre um único change stream para cada collection com pelo menos um trigger. Se vários Triggers estiverem habilitados para uma collection, todos eles compartilharão o mesmo change stream.
Importante
Alterar limitações do stream
Há limites para o número total de change streams que você pode abrir em um cluster, dependendo do tamanho do cluster. Para obter mais informações, consulte limitações change stream.
Além disso, não é possível definir um gatilho de banco de dados de dados ( trigger ) em uma instância sem servidor ou em uma instância do instância do banco de dados federado porque elas não são compatíveis com change streams.
Você controla quais operações fazem com que um trigger seja acionado, bem como o resultado desse acionamento. Por exemplo, você pode executar uma função sempre que um campo específico de um documento for atualizado. A função pode acessar todo o evento de mudança, para que você sempre saiba o que mudou. Você também pode passar o evento de alteração para o AWS EventBridge para lidar com o evento fora do Atlas.
Os acionadores suportam expressões $match para filtrar eventos de alteração e expressões de $project para limitar os dados incluídos em cada evento.
Aviso
Nos triggers de nível de sistema e de banco de dados, é possível configurar triggers de forma a fazer com que outros triggers sejam acionados, resultando em recursão. Por exemplo, um trigger de nível de banco de dados que escreve em uma collection dentro do mesmo banco de dados, ou um registrador ou encaminhador de registros no nível do cluster que escreve registros em outro banco de dados no mesmo cluster.
Criar um gatilho de banco de dados (trigger)
Você pode criar um trigger de banco de dados de dados a partir da UI do Atlas ou com a App Services CLI.
Navegue até a Página Triggers
Se ainda não tiver sido exibido, selecione a organização que contém seu projeto no menu Organizations na barra de navegação.
Se ainda não estiver exibido, selecione seu projeto no menu Projects na barra de navegação.
Na barra lateral, clique em Triggers sob o título Services.
A página Acionadores é exibida.
Clique em Add Trigger para abrir a página de configuração do trigger.
Selecione o tipo de trigger Database .
Configure o trigger e clique em Save.
Autentique um usuário do MongoDB Atlas :
Use sua chave de API de administração do MongoDB Atlas para fazer login na App Services CLI:
appservices login --api-key="<API KEY>" --private-api-key="<PRIVATE KEY>" Extraia os arquivos de configuração mais recentes do seu aplicativo:
Execute o seguinte comando para obter uma cópia local dos seus arquivos de configuração:
appservices pull --remote=<App ID> Por padrão, o comando extrai arquivos para o diretório de trabalho atual. Você pode especificar um caminho de diretório com o sinalizador
--local
opcional.Adicione um trigger arquivo de configuração do de banco de dados de dados ao
triggers
subdiretório em seus arquivos de aplicativo local.Distribua suas alterações:
Execute o seguinte comando para implementar suas alterações:
appservices push
Observação
Atlas não impõe nomes de arquivo específicos para arquivos de configuração de trigger . No entanto, uma vez importado, o Atlas renomeará cada arquivo de configuração para corresponder ao nome do trigger que ele define.
Configuração
Os gatilhos de banco de dados (triggers) têm as seguintes opções de configuração:
Detalhes do trigger
Na seção Trigger Details, você pode selecionar o escopo para o qual deseja que o trigger Watch Against, com base no nível de granularidade que deseja. Suas opções são:
Collection, quando ocorre uma alteração em uma coleta especificada
Database, quando ocorre uma alteração em qualquer coleção em um banco de dados específico
Deployment, quando ocorrem alterações de sistema em um cluster especificado.
Se você selecionar o tipo de origem da implantação, os seguintes bancos de dados não serão observados quanto a alterações:
Os bancos de dados admin
admin
,local
econfig
Os bancos de dados de sincronização
__realm_sync
e__realm_sync_<app_id>
Importante
O tipo de fonte de nível de sistema só está disponível em níveis dedicados.
Dependendo do tipo de fonte que você está usando, as opções adicionais serão diferentes. A tabela a seguir descreve essas opções.
Tipo de fonte | Opções |
---|---|
Collection |
|
Database |
|
Deployment |
|
Dica
Pré-imagens e otimização de desempenho
As pré-imagens exigem uma sobrecarga adicional de armazenamento que pode afetar o desempenho. Se você não estiver usando pré-imagens em uma coleção, desabilite as pré-imagens. Para saber mais, consulte Desabilitar pré-imagens em nível de coleção.
As pré-imagens de documentos são suportadas em clusters Atlas não fragmentados que executam o MongoDB 4.4+ e em clusters Atlas fragmentados que executam o MongoDB 5.3 e posterior. Você pode atualizar um cluster não fragmentado (com pré-imagens) para um cluster fragmentado, desde que o cluster esteja executando a versão 5.3 ou posterior.
Configurações de trigger
Campo | Descrição |
---|---|
Auto-Resume | Se ativado, quando o token de retomada desse trigger não puder ser encontrado no oplog do cluster, o trigger retomará automaticamente os eventos de processamento no próximo evento relevante de change streams. Todos os eventos de change streams, desde quando o trigger foi suspenso até que o trigger retome a execução, não têm o trigger acionado para eles. |
Event Ordering | Se habilitado, os eventos de trigger são processados na ordem em que ocorrem. Se desabilitado, os eventos podem ser processados em paralelo, o que é mais rápido quando muitos eventos ocorrem ao mesmo tempo. Se a ordenação de eventos estiver habilitada, múltiplas execuções desse trigger ocorrerão sequencialmente com base nos carimbos de data/hora dos eventos de alteração. Se a ordenação de eventos estiver desabilitada, múltiplas execuções desse trigger ocorrerão de forma independente. Dica: para melhorar o desempenho dos triggers que respondem a operações de banco de dados de dados em massa, desabilite a ordenação de evento . |
Skip Events On Re-Enable | Desabilitado por padrão. Se habilitado, quaisquer eventos de alteração ocorridos enquanto esse trigger esteve desabilitado não serão processados. |
eventType
Na seção Event Type, você escolhe qual ação será executada quando o trigger for acionado. Você pode optar por executar uma função ou usar o AWS EventBridge.
Avançado
Na seção Advanced, as seguintes opções de configuração opcionais estão disponíveis:
Campo | Descrição | ||||||||
---|---|---|---|---|---|---|---|---|---|
Project Expression | Uma expressão $project que seleciona um subconjunto de campos de cada evento no fluxo de alteração. Você pode usar isso para otimizar a execução do acionador. A expressão é um objeto que mapeia o nome dos campos no evento de alteração para um
| ||||||||
Match Expression | Um documento de expressão $match que o Atlas usa para filtrar quais eventos de alteração fazem com que o trigger seja acionado. O trigger avalia todos os objetos de evento de alteração que recebe em relação a essa expressão de correspondência e só é executado se a expressão for avaliada como O MongoDB executa uma correspondência de igualdade total para documentos incorporados em uma expressão de correspondência. Se quiser corresponder a um campo específico em um documento incorporado, consulte o campo diretamente usando anotação de ponto. Para obter mais informações, consulte Query sobre documentos incorporados no manual do servidor MongoDB. Para otimizar o desempenho, limite o número de campos que o trigger processa usando uma expressão $match . Saiba mais. | ||||||||
Maximum Throughput | Se a fonte de dados vinculada for um servidor dedicado (nível M10+), é possível aumentar a taxa de transferência máxima além dos 10.000 processos simultâneos padrão. Importante: para habilitar a taxa de transferência máxima, é preciso desabilitar a Ordem de eventos. Antes de aumentar a taxa de transferência máxima, considere se um ou mais de seus triggers estão chamando uma API externa com taxa limitada. Aumentar a taxa de trigger pode resultar em exceder esses limites. Aumentar o rendimento também pode adicionar uma carga de trabalho maior, afetando o desempenho geral do cluster. |
Alterar tipos de evento
Eventos de alteração de banco de dados representam alterações individuais em uma collection específica do seu cluster MongoDB Atlas vinculado.
Todo evento de banco de dados tem o mesmo tipo de operação e estrutura do objeto de evento de alteração que foi emitido pelo change stream subjacente. Eventos de mudança têm os seguintes tipos de operação:
Tipo de operação | Descrição |
---|---|
Inserir documento (Todos os tipos de trigger) | Representa um novo documento adicionado à collection. |
Atualizar documento (Todos os tipos de trigger) | Representa uma alteração a um documento existente na collection. |
Excluir documento (todos os tipos de trigger) | Representa um documento excluído da collection. |
Substituir documento (Todos os tipos de trigger) | Representa um novo documento que substituiu um documento na collection. |
Criar collection (somente tipos de trigger de banco de dados e sistema) | Representa a criação de uma nova collection. |
Modificar coleção (somente tipos de gatilho de banco de dados e sistema) | Representa a collection de alteração. |
Renomear collection (somente tipos de trigger de banco de dados e sistema) | Representa a collection sendo renomeada. |
Descartar collection (somente tipos de trigger de banco de dados e sistema) | Representa uma collection sendo descartada. |
Fragmentar collection (somente tipos de trigger de banco de dados e sistema) | Representa uma collection mudando de não fragmentada para fragmentada. |
Refragmentar collection (somente tipos de trigger de banco de dados e sistema) | Representa uma alteração na fragmentação de uma collection. |
Refinar a chave de shard da collection (somente tipos de trigger de banco de dados e sistema) | Representa uma alteração na chave de fragmento de uma coleção. |
Criar índices (somente tipos de trigger de banco de dados e sistema) | Representa a criação de um novo índice. |
Descartar índices (somente tipos de trigger de banco de dados e sistema) | Representa um índice sendo descartado. |
Descartar banco de dados (somente tipo de trigger de sistema) | Representa um banco de dados sendo descartado. |
Objetos de evento de alteração do banco de dados têm o seguinte formato geral:
{ _id : <ObjectId>, "operationType": <string>, "fullDocument": <document>, "fullDocumentBeforeChange": <document>, "ns": { "db" : <string>, "coll" : <string> }, "documentKey": { "_id": <ObjectId> }, "updateDescription": <document>, "clusterTime": <Timestamp> }
Exemplo de gatilho de banco de dados (trigger)
Uma loja online deseja notificar seus clientes sempre que um de seus pedidos muda de local. Eles registram cada pedido na collection store.orders
como um documento semelhante a este:
{ _id: ObjectId("59cf1860a95168b8f685e378"), customerId: ObjectId("59cf17e1a95168b8f685e377"), orderDate: ISODate("2018-06-26T16:20:42.313Z"), shipDate: ISODate("2018-06-27T08:20:23.311Z"), orderContents: [ { qty: 1, name: "Earl Grey Tea Bags - 100ct", price: NumberDecimal("10.99") } ], shippingLocation: [ { location: "Memphis", time: ISODate("2018-06-27T18:22:33.243Z") }, ] }
Para automatizar esse processo, o armazenamento cria um trigger de banco de dados de dados que escuta Update
eventos de alteração na coleção store.orders
. Quando o trigger observa um evento Update
, ele passa o objeto de evento de mudança para sua Função associada, textShippingUpdate
. A função verifica o evento de alteração para quaisquer alterações no campo shippingLocation
e, se ele tiver sido atualizado, envia uma mensagem de texto para o cliente com o novo local do pedido.
{ "type": "DATABASE", "name": "shippingLocationUpdater", "function_name": "textShippingUpdate", "config": { "service_name": "mongodb-atlas", "database": "store", "collection": "orders", "operation_types": ["UPDATE"], "unordered": false, "full_document": true, "match": {} }, "disabled": false }
exports = async function (changeEvent) { // Destructure out fields from the change stream event object const { updateDescription, fullDocument } = changeEvent; // Check if the shippingLocation field was updated const updatedFields = Object.keys(updateDescription.updatedFields); const isNewLocation = updatedFields.some(field => field.match(/shippingLocation/) ); // If the location changed, text the customer the updated location. if (isNewLocation) { const { customerId, shippingLocation } = fullDocument; const mongodb = context.services.get("mongodb-atlas"); const customers = mongodb.db("store").collection("customers"); const { location } = shippingLocation.pop(); const customer = await customers.findOne({ _id: customerId }); const twilio = require('twilio')( // Your Account SID and Auth Token from the Twilio console: context.values.get("TwilioAccountSID"), context.values.get("TwilioAuthToken"), ); await twilio.messages.create({ To: customer.phoneNumber, From: context.values.get("ourPhoneNumber"), Body: `Your order has moved! The new location is ${location}.` }) } };
Triggers suspensos
Gatilhos de banco de dados (triggers) podem entrar em um estado suspenso em resposta a um evento que impede que o change stream do trigger continue. Eventos que podem suspender um trigger incluem:
invalidar eventos como
dropDatabase
,renameCollection
ou aqueles causados por uma interrupção na rede.o token de retomada necessário para retomar o fluxo de alterações não está mais no oplog do cluster. Os logs da aplicação referem-se a isso como um erro
ChangeStreamHistoryLost
.
No evento de um trigger suspenso ou com falha , o Atlas envia ao proprietário do projeto um e-mail alertando-o sobre o problema.
Retomar automaticamente um trigger suspenso
Você pode configurar um trigger para ser retomado automaticamente se o trigger tiver sido suspenso porque o token de retomada não está mais no oplog. O trigger não processa nenhum evento change stream perdido entre o momento em que o token de retomada é perdido e o momento em que o processo de retomada é concluído.
Ao criar ou atualizar um gatilho de banco de dados ( trigger ) na UI do Atlas :
Navegue até a página de configuração do trigger que você deseja retomar automaticamente se for suspenso.
Na seção Advanced (Optional), selecione Auto-Resume Triggers.
Salve e implante as alterações.
Retomar manualmente um trigger suspenso
Quando você retoma manualmente um Gatilho suspenso, seu Aplicativo tenta retomar o Gatilho no próximo evento de fluxo de alteração depois que o fluxo de alterações parou. Se o token de currículo não estiver mais no oplog do cluster, o gatilho deverá ser iniciado sem um token de currículo. Isso significa que o gatilho começa a ouvir novos eventos, mas não processa nenhum evento passado perdido.
Você pode ajustar o tamanho do oplog para manter o token de retomada por mais tempo após uma suspensão dimensionando seu |serviço| cluster. Mantenha um tamanho de oplog algumas vezes maior do que o pico de taxa de transferência de oplog (GB/hora) do cluster para reduzir o risco de que o token de retomada de um trigger suspenso caia do oplog antes da execução do trigger. Visualize a oplog taxa de transferência de do cluster no grafo oplog GBde /hora no |serviço| métricas do cluster.
Você pode reiniciar um trigger suspenso na UI do Atlas ou com a App Services CLI.
No Atlas, vá Triggers para a página do seu projeto.
Se ainda não tiver sido exibido, selecione a organização que contém seu projeto no menu Organizations na barra de navegação.
Se ainda não estiver exibido, selecione seu projeto no menu Projects na barra de navegação.
Na barra lateral, clique em Triggers sob o título Services.
A página Acionadores é exibida.
Reiniciar o gatilho
Clique em Restart na coluna Actions do trigger. Você pode optar por reiniciar o trigger com um token de retomada do fluxo de alterações ou abrir um novo change stream.
Indique se deseja ou não usar um token de retomada e clique em Resume Database Trigger.
Observação: se você usar um token de retomada, o Atlas tentará retomar o change stream do trigger no evento imediatamente após o último evento de alteração processado. Se for bem-sucedido, o trigger processará todos os eventos que ocorreram enquanto ele estava suspenso. Se você não usar um token de retomada, o trigger começará a ouvir novos eventos, mas não disparará para nenhum evento que ocorreu enquanto ele estava suspenso.
Autenticar um usuário do MongoDB Atlas
Use sua chave de API de administração do MongoDB Atlas para fazer login na App Services CLI:
appservices login --api-key="<API KEY>" --private-api-key="<PRIVATE KEY>"
Extraia os arquivos de configuração mais recentes do seu aplicativo
Execute o seguinte comando para obter uma cópia local dos seus arquivos de configuração:
appservices pull --remote=<App ID>
Por padrão, o comando extrai arquivos para o diretório de trabalho atual. Você pode especificar um caminho de diretório com a bandeira --local
opcional.
Verifique se o arquivo de configuração do trigger existe
Se você exportou uma nova cópia do seu aplicação, ela já deverá incluir um arquivo de configuração atualizado para o trigger suspenso . Você pode confirmar que o arquivo de configuração existe procurando no diretório /triggers
por um arquivo de configuração detrigger com o mesmo nome que o trigger.
Relatório de tempo de gatilho
A lista de triggers na UI do Atlas mostra três carimbos de data/hora:
Última modificação
Esta é a hora em que o trigger foi criado ou alterado mais recentemente.
Último Heartbeat
O Atlas acompanha a última vez que um trigger foi executado. Se o trigger não estiver enviando nenhum evento, o servidor enviará uma pulsação para garantir que o token de currículo do trigger permaneça atualizado. Qualquer evento que seja mais recente é mostrado como Latest Heartbeat.
Hora do Último Cluster Processado
O Atlas também mantém o registro de Last Cluster Time Processed, que é a última vez em que o change stream que apoia um trigger emitiu um evento. Ele será mais antigo do que o Latest Heartbeat se não houver nenhum evento desde o heartbeat mais recente.
Otimização de desempenho
Desativar a ordenação de eventos para operações de intermitência
Considere desabilitar a ordenação de eventos se o trigger for acionado em uma collection que recebe rajadas curtas de eventos (por exemplo, inserção de dados como parte de um trabalho em lote diário).
Os Triggers Ordenados esperam para executar uma Função para um evento específico até que as Funções de eventos anteriores tenham terminado de ser executadas. Como consequência, os Triggers Ordenados são efetivamente limitados pelo tempo de execução de cada função do Trigger sequencial. Isso pode causar um atraso significativo entre o evento do banco de dados que aparece no change stream e o acionamento do Trigger. Em alguns casos extremos, os eventos do banco de dados podem cair do oplog antes de um Trigger Ordenado de longa duração processá-los.
Gatilhos não ordenados executam funções em paralelo, se possível, que podem ser consideravelmente mais rápidos (dependendo do seu caso de uso), mas não garante que várias execuções de uma função de gatilho ocorram em ordem de eventos.
Desativar pré-imagens em nível de collection
As pré-imagens de documentos exigem que seu cluster registre dados adicionais sobre cada operação em uma collection. Depois de ativar as pré-imagens para qualquer trigger em uma collection, seu cluster armazena pré-imagens para cada operação na collection.
O espaço de armazenamento adicional e a sobrecarga de computação podem prejudicar o desempenho do acionador , dependendo da configuração do cluster.
Para evitar o armazenamento e a sobrecarga de computação das pré-imagens, você deve desativar as pré-imagens de toda a coleção subjacente do MongoDB. Esta é uma configuração separada de qualquer configuração de pré-imagem de gatilho individual.
Se você desativar as pré-imagens no nível de coleção, nenhum gatilho ativo será ativado essa coleção pode usar pré-imagens. No entanto, se você excluir ou desativar todos os acionadores de pré-imagem em uma coleção, então você também poderá desativar as pré-imagens no nível de coleção.
Para saber como, consulte Desativar Pré-imagens para uma Collection.
Usar Expressões de correspondência para limitar invocações de trigger
Você pode limitar o número de invocações de trigger especificando uma expressão $match no campo Match Expression . O Atlas avalia a expressão de correspondência em relação ao documento de evento de alteração e invoca o trigger somente se a expressão for avaliada como verdadeira para o evento de alteração determinado.
A expressão match é um JSON document que especifica as condições de query usando a sintaxe de query de leitura do MongoDB.
Recomendamos usar apenas expressões de correspondência quando o volume de eventos de gatilho se tornar mensuravelmente um problema de desempenho. Até lá, receba todos os eventos e manuseie-os individualmente no código de função Trigger.
A forma exata do documento do evento de mudança depende do evento que fez o gatilho disparar. Para obter detalhes, consulte a referência para cada tipo de evento:
A expressão de correspondência a seguir permite que o trigger dispare somente se o objeto de evento de alteração especificar que o campo status
em um documento foi alterado.
updateDescription
é um campo do objeto Atualizar evento.
{ "updateDescription.updatedFields.status": { "$exists": true } }
A expressão de correspondência a seguir permite que o Trigger seja acionado somente quando o campo needsTriggerResponse
de um documento for true
. O campo fullDocument
dos eventos inserir, atualizar e substituir representa um documento após a operação mostrada. Para receber o campo fullDocument
, você deve habilitar Full Document na configuração do Trigger.
{ "fullDocument.needsTriggerResponse": true }
Testando Expressões de Correspondência
O procedimento a seguir mostra uma maneira de testar se a expressão correspondente funciona como esperado:
Baixe o MongoDB Shell (mongosh) e use-o para se conectar ao seu cluster.
Substituindo
DB_NAME
pelo nome do banco de dados,COLLECTION_NAME
pelo seu nome da collection eYOUR_MATCH_EXPRESSION
pela expressão de correspondência que você deseja testar, cole o seguinte no mongosh para abrir um change stream em uma collection existente:db.getSiblingDB(DB_NAME).COLLECTION_NAME.watch([{$match: YOUR_MATCH_EXPRESSION}]) while (!watchCursor.isClosed()) { if (watchCursor.hasNext()) { print(tojson(watchCursor.next())); } } Em outra janela do terminal, use
mongosh
para fazer alterações em alguns documentos de teste na coleção.Observe o que o change stream filtra para dentro e para fora.
Usar expressões de projeto para reduzir o tamanho dos dados de entrada
No campo Project Expression, limite o número de campos que o gatilho processa utilizando uma expressão $project.
Observação
O projeto é apenas inclusivo
Ao usar Triggers, uma expressão de projeção é apenas inclusiva. O projeto não suporta a mistura de inclusões e exclusões. A expressão do projeto deve ser inclusiva porque os triggers exigem que você inclua operationType
.
Se você quiser excluir um único campo, a expressão de projeção deverá incluir todos os campos, exceto aquele que você deseja excluir. Você só pode excluir explicitamente _id
, que está incluído por padrão.
Um gatilho é configurado com os seguintes Project Expression:
{ "_id": 0, "operationType": 1, "updateDescription.updatedFields.status": 1 }
O objeto de evento de mudança que o Atlas passa para a função de trigger inclui somente os campos especificados na projeção, como no exemplo a seguir :
{ "operationType": "update", "updateDescription": { "updatedFields": { "status": "InProgress" } } }