Pular para o conteúdo
@aws/nx-plugin
Blog

TypeScript Agent para Banco de Dados Relacional

O gerador connection conecta um TypeScript Agent a um projeto de Banco de Dados Relacional, disponibilizando um cliente Prisma dentro da sua fábrica de agente.

Pré-requisitos

Seção intitulada “Pré-requisitos”

Antes de usar este gerador, certifique-se de ter:

  1. Um projeto ts#agent
  2. Um projeto ts#rdb

Uso

Seção intitulada “Uso”

Executar o Gerador

Seção intitulada “Executar o Gerador”
  1. Instale o Nx Console VSCode Plugin se ainda não o fez
  2. Abra o console Nx no VSCode
  3. Clique em Generate (UI) na seção "Common Nx Commands"
  4. Procure por @aws/nx-plugin - connection
  5. Preencha os parâmetros obrigatórios
    • Clique em Generate

    Selecione seu projeto Agent como origem e seu projeto de banco de dados relacional como destino. Se o projeto contiver múltiplos componentes de agente, especifique sourceComponent para desambiguar.

    Opções

    Seção intitulada “Opções”
    ParâmetroTipoPadrãoDescrição
    sourceProject Obrigatóriostring-O projeto de origem
    targetProject Obrigatóriostring-O projeto de destino para conectar
    sourceComponent string-O componente de origem para conectar (nome do componente, caminho relativo à raiz do projeto de origem, ou id do gerador). Use '.' para selecionar explicitamente o projeto como origem.
    targetComponent string-O componente de destino para conectar (nome do componente, caminho relativo à raiz do projeto de destino, ou id do gerador). Use '.' para selecionar explicitamente o projeto como destino.
    preferInstallDependencies booleantrueSe deve preferir instalar dependências após a execução do gerador. Defina como false para adiar a instalação ao executar múltiplos geradores em lote (uma instalação ainda é executada se necessário para que os geradores subsequentes possam calcular o grafo de projetos Nx); instale uma vez no final.

    Saída do Gerador

    Seção intitulada “Saída do Gerador”

    O gerador modifica dois arquivos no diretório de origem do seu agente:

    • Directorypackages/my-service/src/my-agent
      • agent.ts Cliente Prisma buscado dentro de getAgent e disponível para ferramentas
      • Dockerfile Pacote CA do RDS instalado para conexões SSL ao Aurora

    Além disso, o alvo <agent-name>-dev do agente é atualizado para depender do alvo dev do banco de dados.

    Usando o Banco de Dados nas Ferramentas do Agente

    Seção intitulada “Usando o Banco de Dados nas Ferramentas do Agente”

    O cliente Prisma é instanciado dentro de getAgent(). Como o gerador ts#agent configura um único Agent por sessão, o cliente também é reutilizado durante o tempo de vida da sessão:

    packages/my-service/src/my-agent/agent.ts
    import { getPrisma as getMyDb } from ':my-scope/my-db';
    

    export const getAgent = async () => {
      const myDb = await getMyDb();
      // ...
      return new Agent({ /* use myDb in tools */ });
    };

    Múltiplos Bancos de Dados

    Seção intitulada “Múltiplos Bancos de Dados”

    Executar o gerador novamente com um destino diferente adiciona o segundo banco de dados junto com o primeiro:

    packages/my-service/src/my-agent/agent.ts
    import { getPrisma as getMyDb } from ':my-scope/my-db';
    import { getPrisma as getOtherDb } from ':my-scope/other-db';
    

    export const getAgent = async () => {
      const myDb = await getMyDb();
      const otherDb = await getOtherDb();
      // ...
      return new Agent({ /* use both clients in tools */ });
    };

    Infraestrutura

    Seção intitulada “Infraestrutura”

    O construto de agente gerado implementa IGrantable e IConnectable, então você pode conceder acesso de rede e IAM ao banco de dados diretamente no construto.

    packages/infra/src/stacks/application-stack.ts
    import { RuntimeNetworkConfiguration } from 'aws-cdk-lib/aws-bedrockagentcore';
    import { MyDatabase } from ':my-scope/common-constructs';
    

    const db = new MyDatabase(this, 'Db', { vpc, ... });
    

    const myAgent = new MyAgent(this, 'MyAgent', {
      networkConfiguration: RuntimeNetworkConfiguration.usingVpc(this, {
        vpc,
        vpcSubnets: { subnetType: SubnetType.PRIVATE_WITH_EGRESS },
      }),
    });
    

    db.allowDefaultPortFrom(myAgent);
    db.grantConnect(myAgent);

    allowDefaultPortFrom abre a regra do grupo de segurança para que o runtime do agente possa alcançar a porta do banco de dados. grantConnect concede permissão IAM rds-db:connect à função de execução do agente.

    Requisitos SSL ao Conectar Sem RDS Proxy

    Seção intitulada “Requisitos SSL ao Conectar Sem RDS Proxy”

    O gerador de conexão atualiza o Dockerfile para instalar o pacote de CA do Amazon RDS em /usr/local/share/ca-certificates/rds-bundle.crt. Defina NODE_EXTRA_CA_CERTS para esse caminho para que o Node.js confie no certificado ao conectar sem RDS Proxy:

    packages/infra/src/stacks/application-stack.ts
    new MyAgent(this, 'MyAgent', {
      ...
      environmentVariables: {
        NODE_EXTRA_CA_CERTS: '/usr/local/share/ca-certificates/rds-bundle.crt',
      },
    });

    Para mais detalhes, consulte a documentação SSL/TLS do Amazon RDS. Ao usar RDS Proxy, você não precisa configurar NODE_EXTRA_CA_CERTS.

    Desenvolvimento Local

    Seção intitulada “Desenvolvimento Local”
    Terminal window
    pnpm nx <agent-name>-dev <project-name>

    Isso inicia o agente e todos os bancos de dados conectados. A variável de ambiente LOCAL_DEV=true faz com que cada cliente Prisma se conecte ao seu banco de dados Docker local em vez do Aurora.