Tutorial: Usar uma função do Lambda para acessar um banco de dados Amazon RDS

Neste tutorial, você usará uma função do Lambda para gravar dados em um banco de dados do Amazon Relational Database Service (Amazon RDS) por meio do RDS Proxy. Sua função do Lambda lê registros de uma fila do Amazon Simple Queue Service (Amazon SQS) e grava um novo item em uma tabela no banco de dados sempre que uma mensagem é adicionada. Neste exemplo, você usa o AWS Management Console para adicionar mensagens manualmente à sua fila. O diagrama a seguir mostrará os recursos da AWS que você usará para concluir o tutorial.

Com o Amazon RDS, você pode executar um banco de dados relacional gerenciado na nuvem usando produtos de banco de dados comuns, como Microsoft SQL Server, MariaDB, MySQL, Oracle Database e PostgresQL. Ao usar o Lambda para acessar seu banco de dados, você pode ler e gravar dados em resposta a eventos, como um novo cliente se registrando em seu site. Sua função, a instância de banco de dados e o proxy escalam automaticamente para atender a períodos de alta demanda.

Para concluir este tutorial, realize as seguintes tarefas:

1. Inicie uma instância de banco de dados do RDS para MySQL e um proxy na VPC padrão de sua Conta da AWS.

2. Crie e teste uma função do Lambda que cria uma nova tabela em seu banco de dados e grava dados nela.

3. Crie uma fila do Amazon SQS e configure-a para invocar sua função do Lambda sempre que uma nova mensagem for adicionada.

4. Teste a configuração completa adicionando mensagens à fila por meio do AWS Management Console e monitorando os resultados com o CloudWatch Logs.

Ao concluir essas etapas, você aprende a:

• Como usar o Amazon RDS para criar uma instância de banco de dados e um proxy e conectar uma função do Lambda ao proxy.

• Como usar o Lambda para realizar operações de criação e leitura em um banco de dados do Amazon RDS.

• Como usar o Amazon SQS para invocar uma função do Lambda.

Você pode concluir este tutorial usando o AWS Management Console ou a AWS Command Line Interface (AWS CLI).

Pré-requisitos

Antes de começar, conclua as etapas nas seguintes seções:

• Cadastre-se em uma Conta da AWS

• Criar um usuário com acesso administrativo

Criar uma instância de banco de dados do Amazon RDS

Uma instância de banco de dados do Amazon RDS é um ambiente de banco de dados isolado em execução na Nuvem AWS. Uma instância pode conter um ou mais bancos de dados criados pelo usuário. A menos que você especifique o contrário, o Amazon RDS cria instâncias de banco de dados na VPC padrão incluída em sua Conta da AWS. Para receber mais informações sobre o Amazon VPC, consulte o Guia do usuário do Amazon Virtual Private Cloud.

Neste tutorial, você cria uma nova instância na VPC padrão de sua Conta da AWS e cria um banco de dados com o nome ExampleDB nessa instância. Você pode criar o banco de dados e a respectiva instância usando o AWS Management Console ou a AWS CLI.

Como criar uma instância de banco de dados

1. No console do Amazon RDS, selecione Criar banco de dados.

2. Deixe a opção Criação padrão selecionada e, em Opções do mecanismo, escolha MySQL.

3. Na seção Modelos, escolha Nível gratuito.

4. Em Configurações, para o identificador da instância de banco de dados, digite MySQLForLambda.

5. Para definir seu nome de usuário e senha, faça o seguinte:

   1. Em Configurações de credenciais, deixe o Nome do usuário principal definido como admin.

   2. Para a Senha mestra, digite e confirme uma senha para acessar seu banco de dados.

6. Para especificar o nome do banco de dados, faça o seguinte:

   • Deixe todas as opções padrão restantes selecionadas e role para baixo até a seção Configuração adicional.

   • Expanda essa seção e insira ExampleDB como o Nome do banco de dados inicial.

7. Deixe todas as opções padrão restantes selecionadas e escolha Criar banco de dados.

Criar a função do Lambda e o proxy

É possível usar o console do RDS para criar uma função do Lambda e um proxy na mesma VPC do banco de dados.

nota

Você só pode criar esses recursos associados quando o banco de dados tiver concluído a criação e estiver no status Disponível.

Como criar uma função e um proxy associados

1. Na página Bancos de dados, confira se o banco de dados está no status Disponível. Se estiver, vá para a próxima etapa. Caso contrário, espere até que o banco de dados esteja disponível.

2. Selecione o banco de dados e escolha Configurar conexão do Lambda em Ações.

3. Na página Configurar conexão do Lambda, selecione Criar nova função.

   Defina o Nome da nova função do Lambda como LambdaFunctionWithRDS.

4. Na seção RDS Proxy, selecione a opção Conectar usando o RDS Proxy. Selecione ainda Criar proxy.

   • Em Credenciais do banco de dados, selecione Nome do usuário e senha do banco de dados.

   • Em Nome do usuário, especifique admin.

   • Em Senha, digite a senha que você criou para a instância de banco de dados.

5. Selecione Configurar para concluir a criação da função do Lambda e do proxy.

O assistente conclui a configuração e fornece um link para o console do Lambda para você examinar a nova função. Observe o endpoint do proxy antes de mudar para o console do Lambda.

Criar um perfil de execução de função

Antes de criar sua função do Lambda, você cria um perfil de execução para dar à sua função as permissões necessárias. Neste tutorial, o Lambda precisa de permissão para gerenciar a conexão de rede com a VPC que contém a instância de banco de dados e para pesquisar mensagens de uma fila do Amazon SQS.

Para dar à sua função do Lambda as permissões necessárias, este tutorial usa políticas gerenciadas pelo IAM. Essas são políticas que concedem permissões para muitos casos de uso comuns e estão disponíveis na sua Conta da AWS. Para obter mais informações sobre políticas gerenciadas, consulte Melhores práticas de política.

Para criar o perfil de execução do Lambda

1. Abra a página Perfis do console do IAM e escolha Criar perfil.

2. Em Tipo de entidade confiável, selecione Serviço da AWS e, em Caso de uso, escolha Lambda.

3. Escolha Próximo.

4. Para adicionar as políticas gerenciadas do IAM, faça o seguinte:

   1. Usando a caixa de pesquisa de políticas, pesquise AWSLambdaSQSQueueExecutionRole.

   2. Na lista de resultados, marque a caixa de seleção ao lado do perfil e escolha Limpar filtros.

   3. Usando a caixa de pesquisa de políticas, pesquise AWSLambdaVPCAccessExecutionRole.

   4. Na lista de resultados, marque a caixa de seleção ao lado do perfil e escolha Avançar.

5. Em Nome do perfil, digite lambda-vpc-sqs-role e escolha Criar perfil.

Posteriormente no tutorial, você precisará do nome do recurso da Amazon (ARN) do perfil de execução que acabou de criar.

Para encontrar o ARN do perfil de execução

1. Abra a página Perfis do console do IAM e escolha o perfil (lambda-vpc-sqs-role).

2. Copie o ARN exibido na seção Resumo.

Criar o pacote de implantação do Lambda

O exemplo de código Python a seguir usa o pacote PyMySQL para abrir uma conexão com seu banco de dados. Na primeira vez que você invoca sua função, ela também cria uma nova tabela chamada Customer. A tabela usa o seguinte esquema, em que CustID é a chave primária:

Customer(CustID, Name)

A função também usa a PyMySQL para adicionar registros a essa tabela. A função adiciona registros usando os IDs de clientes e nomes especificados nas mensagens que você adicionará à sua fila do Amazon SQS.

O código cria a conexão com seu banco de dados fora da função do manipulador. A criação da conexão no código de inicialização permite que a conexão seja reutilizada por invocações subsequentes de sua função e melhora o desempenho. Em um aplicativo de produção, você também pode usar a simultaneidade provisionada para inicializar um número solicitado de conexões de banco de dados. Essas conexões estão disponíveis assim que sua função é invocada.

import sys
import logging
import pymysql
import json
import os

# rds settings
user_name = os.environ['USER_NAME']
password = os.environ['PASSWORD']
rds_proxy_host = os.environ['RDS_PROXY_HOST']
db_name = os.environ['DB_NAME']

logger = logging.getLogger()
logger.setLevel(logging.INFO)

# create the database connection outside of the handler to allow connections to be
# re-used by subsequent function invocations.
try:
        conn = pymysql.connect(host=rds_proxy_host, user=user_name, passwd=password, db=db_name, connect_timeout=5)
except pymysql.MySQLError as e:
    logger.error("ERROR: Unexpected error: Could not connect to MySQL instance.")
    logger.error(e)
    sys.exit(1)

logger.info("SUCCESS: Connection to RDS for MySQL instance succeeded")

def lambda_handler(event, context):
    """
    This function creates a new RDS database table and writes records to it
    """
    message = event['Records'][0]['body']
    data = json.loads(message)
    CustID = data['CustID']
    Name = data['Name']

    item_count = 0
    sql_string = f"insert into Customer (CustID, Name) values(%s, %s)"

    with conn.cursor() as cur:
        cur.execute("create table if not exists Customer ( CustID  int NOT NULL, Name varchar(255) NOT NULL, PRIMARY KEY (CustID))")
        cur.execute(sql_string, (CustID, Name))
        conn.commit()
        cur.execute("select * from Customer")
        logger.info("The following items have been added to the database:")
        for row in cur:
            item_count += 1
            logger.info(row)
    conn.commit()

    return "Added %d items to RDS for MySQL table" %(item_count)
    

nota

Neste exemplo, suas credenciais de acesso ao banco de dados são armazenadas como variáveis ​​de ambiente. Em aplicações de produção, recomendamos que você use o AWS Secrets Manager como uma opção mais segura. Observe que, se sua função do Lambda estiver em uma VPC, para se conectar ao Secrets Manager, será necessário criar um endpoint da VPC. Consulte Como se conectar ao serviço Secrets Manager em uma nuvem privada virtual para saber mais.

Para incluir a dependência da PyMySQL em seu código de função, crie um pacote de implantação .zip. Os seguintes comandos funcionam para Linux, macOS ou Unix:

Para criar um pacote de implantação .zip

1. Salve o exemplo de código como um arquivo denominado lambda_function.py.

2. No mesmo diretório em que você criou seu arquivo lambda_function.py, crie um novo diretório chamado package e instale a biblioteca PyMySQL.

   mkdir package
   pip install --target package pymysql

3. Crie um arquivo zip contendo o código do seu aplicativo e a biblioteca PyMySQL. No Linux ou no macOS, execute os comandos da CLI a seguir. No Windows, use sua ferramenta de zip preferida para criar o arquivo lambda_function.zip. O arquivo de código-fonte lambda_function.py e as pastas que contêm as dependências devem ser instaladas na raiz do arquivo .zip.

   cd package
   zip -r ../lambda_function.zip .
   cd ..
   zip lambda_function.zip lambda_function.py

   Você também pode criar seu pacote de implantação usando um ambiente virtual Python. Consulte Implementar funções do Lambda em Python com arquivos .zip.

Atualizar a função do Lambda

Com o pacote .zip que acabou de criar, você atualizará a função do Lambda usando o console do Lambda. Para permitir que a função acesse o banco de dados, você também precisa configurar variáveis ​​de ambiente com as credenciais de acesso.

Como atualizar a função do Lambda

1. Abra a página Funções do console do Lambda e selecione sua função LambdaFunctionWithRDS.

2. Na guia Configurações de tempo de execução, selecione Editar para alterar o Tempo de execução da função para Python 3.10.

3. Altere o Manipulador para lambda_function.lambda_handler.

4. Na guia Código, selecione Fazer upload de e, depois, arquivo .zip.

5. Selecione o arquivo lambda_function.zip que você criou no estágio anterior e escolha Salvar.

Agora configure a função com o perfil de execução que você criou anteriormente. Isso concede à função as permissões necessárias para acessar sua instância de banco de dados e pesquisar uma fila do Amazon SQS.

Como configurar o perfil de execução da função.

1. Na página Funções do console do Lambda, selecione a guia Configuração e escolha Permissões.

2. No painel Papel de execução, selecione Editar.

3. Em Função existente, selecione a função de execução (lambda-vpc-sqs-role).

4. Escolha Salvar.

Como configurar as variáveis ​​de ambiente da função

1. Na página Funções do console do Lambda, selecione a guia Configuração e, em seguida, escolha Variáveis de ambiente.

2. Selecione a opção Editar.

3. Para adicionar as credenciais de acesso ao banco de dados, faça o seguinte:

   1. Escolha Adicionar variável de ambiente e, em seguida, para Chave, insira USER_NAME, e para Valor, insira admin.

   2. Escolha Adicionar variável de ambiente e, em seguida, para Chave, insira DB_NAME, e para Valor, insira ExampleDB.

   3. Escolha Adicionar variável de ambiente e, em seguida, para Chave, insira PASSWORD, e para Valor, insira a senha escolhida ao criar seu banco de dados.

   4. Selecione Adicionar variáveis de ambiente. Em Chave, insira RDS_PROXY_HOST e, em Valor, insira o endpoint do RDS Proxy que você anotou anteriormente.

   5. Escolha Salvar.

Teste sua função do Lambda no console

Agora você pode usar o console do Lambda para testar sua função. Você cria um evento de teste que imita os dados que sua função receberá ao invocá-la usando o Amazon SQS na fase final do tutorial. Seu evento de teste contém um objeto JSON especificando um ID de cliente e um nome de cliente para adicionar à tabela Customer que sua função cria.

Para testar a função do Lambda

1. Abra a página Funções do console do Lambda e escolha sua função.

2. Selecione a seção Testar.

3. Selecione Criar novo evento e insira myTestEvent como nome do evento.

4. Copie o código a seguir no JSON do evento e escolha Salvar.

   {
     "Records": [
       {
         "messageId": "059f36b4-87a3-44ab-83d2-661975830a7d",
         "receiptHandle": "AQEBwJnKyrHigUMZj6rYigCgxlaS3SLy0a...",
         "body": "{\n     \"CustID\": 1021,\n     \"Name\": \"Martha Rivera\"\n}",
         "attributes": {
           "ApproximateReceiveCount": "1",
           "SentTimestamp": "1545082649183",
           "SenderId": "AIDAIENQZJOLO23YVJ4VO",
           "ApproximateFirstReceiveTimestamp": "1545082649185"
         },
         "messageAttributes": {},
         "md5OfBody": "e4e68fb7bd0e697a0ae8f1bb342846b3",
         "eventSource": "aws:sqs",
         "eventSourceARN": "arn:aws:sqs:us-west-2:123456789012:my-queue",
         "awsRegion": "us-west-2"
       }
     ]
   }

5. Escolha Testar.

Na guia Resultados da execução, você verá resultados semelhantes aos seguintes exibidos nos Logs da função:

[INFO] 2023-02-14T19:31:35.149Z bdd06682-00c7-4d6f-9abb-89f4bbb4a27f The following items have been added to the database:
[INFO] 2023-02-14T19:31:35.149Z bdd06682-00c7-4d6f-9abb-89f4bbb4a27f (1021, 'Martha Rivera')

Criar uma fila do Amazon SQS

Você testou com sucesso a integração da sua função do Lambda e da instância do banco de dados do Amazon RDS. Agora você cria a fila do Amazon SQS que usará para invocar sua função do Lambda na fase final do tutorial.

Para criar uma fila do Amazon SQS (console)

1. Abra a página Filas do console do Amazon SQS e selecione Criar fila.

2. Deixe o Tipo como Padrão e insira LambdaRDSQueue como o nome da sua fila.

3. Mantenha todas as opções padrão selecionadas e escolha Criar fila.

Crie um mapeamento da origem do evento para invocar sua função do Lambda

Um mapeamento da origem do evento é um recurso no Lambda que lê itens de um fluxo ou de uma fila e invoca uma função do Lambda. Ao configurar um mapeamento da origem do evento, você pode especificar um tamanho de lote para que os registros do seu fluxo ou da sua fila sejam agrupados em uma única carga útil. Neste exemplo, você define o tamanho do lote como 1 para que sua função do Lambda seja invocada toda vez que você enviar uma mensagem para sua fila. Você pode configurar o mapeamento da origem do evento usando a AWS CLI ou o console do Lambda.

Crie um mapeamento da origem do evento (console)

1. Abra a página Funções do console do Lambda e escolha sua função (LambdaFunctionWithRDS).

2. Na seção Visão geral da função, selecione Adicionar gatilho.

3. Para a origem, selecione Amazon SQS e, depois, o nome da fila (LambdaRDSQueue).

4. Em Tamanho do lote, insira 1.

5. Deixe todas as outras opções definidas com os valores padrão e escolha Adicionar.

Agora você está pronto para testar sua configuração completa adicionando uma mensagem à sua fila do Amazon SQS.

Teste e monitore sua configuração

Para testar sua configuração completa, adicione mensagens à sua fila do Amazon SQS usando o console. Em seguida, você usa o CloudWatch Logs para confirmar que sua função do Lambda está gravando registros em seu banco de dados conforme o esperado.

Para testar e monitorar sua configuração

1. Abra a página Filas do console do Amazon SQS e selecione sua fila (LambdaRDSQueue).

2. Selecione Enviar e receber mensagens e cole o JSON a seguir no Corpo da mensagem na seção Enviar mensagem.

   {
       "CustID": 1054,
       "Name": "Richard Roe"
   }

3. Escolha Send Message (Enviar mensagem).

   Enviar sua mensagem para a fila fará com que o Lambda invoque sua função por meio do mapeamento da origem do evento. Para confirmar que o Lambda invocou sua função conforme o esperado, use o CloudWatch Logs para verificar se a função gravou o nome e o ID do cliente na tabela do banco de dados:

4. Abra a página Grupos de logs do console do CloudWatch e selecione o grupo de logs para sua função (/aws/lambda/LambdaFunctionWithRDS).

5. No painel Fluxos de logs, selecione o fluxo de logs mais recente.

   Sua tabela deve conter dois registros de clientes, um de cada invocação de sua função. No fluxo de logs, você deverá ver mensagens semelhantes às seguintes:

   [INFO] 2023-02-14T19:06:43.873Z 45368126-3eee-47f7-88ca-3086ae6d3a77 The following items have been added to the database:
   [INFO] 2023-02-14T19:06:43.873Z 45368126-3eee-47f7-88ca-3086ae6d3a77 (1021, 'Martha Rivera')
   [INFO] 2023-02-14T19:06:43.873Z 45368126-3eee-47f7-88ca-3086ae6d3a77 (1054, 'Richard Roe')

Limpe os recursos

Agora você pode excluir os recursos criados para este tutorial, a menos que queira mantê-los. Excluindo os recursos da AWS que você não está mais usando, você evita cobranças desnecessárias em sua conta da AWS.

Como excluir a função do Lambda

1. Abra a página Functions (Funções) no console do Lambda.

2. Selecione a função que você criou.

3. Escolha Ações, Excluir.

4. Escolha Excluir.

Para excluir a função de execução

1. Abra a página Roles (Funções) no console do IAM.

2. Selecione a função de execução que você criou.

3. Clique em Excluir função.

4. Depois em Sim, excluir.

Para excluir a instância de banco de dados MySQL do

1. Abrir oPágina Bancos de dadosdo console do Amazon RDS.

2. Selecione o banco de dados que você criou.

3. Escolha Ações, Excluir.

4. Desmarque a caixa de seleção Create final snapshot (Criar snapshot final).

5. Digite delete me na caixa de texto.

6. Escolha Excluir.

Para excluir a fila do Amazon SQS

1. Faça login no AWS Management Console e abra o console do Amazon SQS em https://console.aws.amazon.com/sqs/.

2. Selecione a fila que você criou.

3. Escolha Excluir.

4. Digite delete na caixa de texto.

5. Escolha Excluir.