Melhores práticas

Práticas recomendadas para atividades Database, que cobrem strings de conexão para SQL Server, Oracle, MySQL e outros bancos de dados, procedimentos armazenados e solução de problemas.

Uso de um procedimento armazenado com o OracleRefCursor

Ao usar procedimentos armazenados no Oracle, certifique-se de que o REF CURSOR esteja corretamente associado à variável Oracle.ManagedDataAccess.Types.OracleRefCursor.

Para fazer isso, você precisa garantir que o número de parâmetros e seu tipo correspondam aos configurados na propriedade Parâmetros da atividade Run Query.

Você pode obter o conteúdo do cursor usando a atividade Invoke Code ou pode passá-lo a outra consulta de banco de dados como um parâmetro de entrada. Aqui está um exemplo de Invoke Code para convertê-lo em uma tabela de dados:

Oracle.ManagedDataAccess.Client.OracleDataReader reader2 = myRefCursor.GetDataReader();
                dt = new DataTable();
                dt.Load(reader2);

Você deve descartar o cursor quando terminar com ele. Você pode fazer isso com a atividade Invoke Code (myRefCursor.Dispose), com a atividade Invoke Method do pacote de atividades System ou por meio de um comando SQL que você executa.

Execução de procedimentos armazenados com parâmetros

As atividades Run Query e Run Command podem chamar um procedimento armazenado em vez de uma instrução SQL simples. Use Run Query quando o procedimento retornar um conjunto de resultados e Run Command quando isso não acontecer.

Para chamar um procedimento armazenado:

1. Defina a propriedade Tipo de comando como Procedimento armazenado.
2. Insira o nome do procedimento no campo SQL , sem EXEC wrapper CALL .
3. Adicione uma entrada à coleção Parâmetros para cada parâmetro de procedimento.

Cada entrada de Parâmetros tem os seguintes atributos:

• Um nome.
• Uma direção (In, Out ou In/Out).
• Um tipo.
• Um valor.

Os valores Out e In/Out são lidos de volta após a chamada. A forma como os nomes e a ordem dos parâmetros são interpretados depende do provedor do banco de dados, portanto, a orientação difere por banco de dados nas seções a seguir.

Banco de Dados	Provedor	Como chamar	Associação de parâmetros
Microsoft SQL Server	Microsoft.Data.SqlClient	Tipo de comando = Procedimento Armazenado, SQL = nome do procedimento	Por nome (@name); a ordem não importa
Oracle	Oracle.ManagedDataAccess.Client	Tipo de comando = Procedimento Armazenado, SQL = nome do procedimento	Por posição; adicionar parâmetros na ordem declarada do procedimento
MySQL/ MariaDB	Abrir conectividade de banco de dados (ODBC)	Tipo de comando = Text, SQL = CALL procedure_name(?, ?)	Espaços reservados posicionais ?
PostgreSQL	ODBC	Tipo de comando = Text, SELECT * FROM function_name(?) ou CALL procedure_name(?)	Espaços reservados posicionais ?
SQLite	Microsoft.Data.Sqlite	Não aplicável	SQLite não tem procedimentos armazenados

Microsoft SQL Server

O SQL Server vincula parâmetros por nome, então os nomes de entrada Parâmetros devem corresponder aos parâmetros com prefixo @do procedimento, e sua ordem não importa. Os parâmetros de saída são retornados quando você define a direção de entrada como Out.

CREATE PROCEDURE dbo.usp_CountCustomers @Country NVARCHAR(5), @Total INT OUTPUT AS
BEGIN
    SET NOCOUNT ON;
    SELECT @Total = COUNT(*) FROM dbo.customer WHERE country = @Country;
END;

Configure Executar Comando com tipo de Comando = Procedimento Armazenado e SQL = dbo.usp_CountCustomers, em seguida, adicione os parâmetros:

Name	Direction	Tipo	Valor
@Country	Em	String	US
@Total	Out	Int32	—

Após a execução, @Total mantém a contagem. Para um procedimento que retorna linhas, use Run Query ; o resultado está disponível na saída de Tabela de dados .

Oracle

O Oracle vincula parâmetros por posição, não por nome, então você deve adicionar as entradas Parâmetros na mesma ordem que o procedimento as declara. Um procedimento retorna um conjunto de resultados por meio de um parâmetro OUT SYS_REFCURSOR ; declare essa entrada com o tipo OracleRefCursor e a direção Out , e as linhas são retornadas na saída Tabela de dados de Run Query. Consulte também Uso de um procedimento armazenado com o OracleRefCursor.

CREATE OR REPLACE PROCEDURE get_customers(p_country IN VARCHAR2, p_cursor OUT SYS_REFCURSOR) AS
BEGIN
    OPEN p_cursor FOR SELECT id, name FROM customer WHERE country = p_country ORDER BY id;
END;

Configure Run Query com tipo de Comando = Procedimento Armazenado e SQL = get_customers, em seguida, adicione os parâmetros na ordem de declaração:

Name	Direction	Tipo	Valor
p_country	Em	String	US
p_cursor	Out	OracleRefCursor	—

AVISO:

O Oracle vincula parâmetros por posição. Se as entradas de Parâmetros não estiverem na ordem declarada do procedimento, os valores serão atribuídos aos parâmetros errados e a chamada falhará ou retornará uma saída vazia.

MySQL e MariaDB

Quando você se conectar ao MySQL ou MariaDB por meio do ODBC, chame o procedimento com o tipo de comando de Texto e uma instrução CALL que usa placeholders ? . Um SELECT dentro do procedimento é retornado na saída Tabela de dados de Run Query.

CREATE PROCEDURE list_customers(IN p_country VARCHAR(5))
BEGIN
    SELECT id, name FROM customer WHERE country = p_country ORDER BY id;
END

Configure Executar Consulta com o tipo de comando = Text e consulta SQL = CALL list_customers(?) e, em seguida, adicione um parâmetro In para o espaço reservado.

Observação:

Para procedimentos do MySQL com parâmetros OUT , leia o valor de um conjunto de resultados retornado ou use o padrão CALL procedure_name(?, @out); SELECT @out; , porque os valores OUT nem sempre são mapeados de volta para a entrada do parâmetro por meio do ODBC.

PostgreSQL

O PostgreSQL expõe dois tipos de rotinas: funções, chamadas com SELECT, e procedimentos, chamados com CALL. Quando você se conectar por meio de ODBC, use o tipo de comando de Texto com placeholders ? posicionais. Use Run Query para uma função que retorna linhas.

CREATE FUNCTION get_customers_by_country(p_country text)
RETURNS TABLE(id int, name text) LANGUAGE sql AS $$
    SELECT id, name FROM customer WHERE country = p_country ORDER BY id;
$$;

Configure Executar Consulta com o tipo de comando = Text e consulta SQL = SELECT * FROM get_customers_by_country(?) e, em seguida, adicione um parâmetro In . Para invocar um procedimento criado com CREATE PROCEDURE, use CALL procedure_name(?) em vez disso.

SQLite

O SQLite não é compatível com procedimentos armazenados. Mantenha a lógica no seu fluxo de trabalho usando instruções Run Query e Run Command com parâmetros ou defina uma visualização reutilizável.

Strings de conexão para diferentes sistemas de banco de dados

Este guia fornece exemplos de strings de conexão para a atividade Connect to Database , permitindo que você se conecte a vários bancos de dados usando drivers nativos e ODBC. Inclui exemplos de string de conexão para:

• Microsoft SQL Server (incluindo a autenticação do Microsoft Entra ID)
• Oracle
• PostgreSQL
• MySQL
• Amazon Amazonas Azure
• Microsoft Access
• SAP HANA
• IBM Db2
• SQLite

Uma seção de solução de problemas para erros de conexão comuns segue os exemplos. Siga as práticas recomendadas para garantir uma conectividade segura e eficiente do banco de dados.

Microsoft SQL Server

Formatos de string de conexão comuns para o Microsoft SQL Server ao usar o Microsoft.Data.SqlClient.

Autenticação do SQL Server e ODBC

1. Usando a autenticação do SQL Server:

   Data Source=SERVER_NAME;Initial Catalog=DATABASE_NAME;User ID=USERNAME;Password=<your-password>;

2. Com uma porta específica:

   Data Source=SERVER_NAME,PORT_NUMBER;Initial Catalog=DATABASE_NAME;User ID=USERNAME;Password=<your-password>;

3. Uso do driver ODBC:

   Driver={ODBC Driver 18 for SQL Server};Server=SERVER_NAME;Database=DATABASE_NAME;Uid=USERNAME;Pwd=<your-password>;Encrypt=yes;TrustServerCertificate=no;

Importante:

Por padrão, essas atividades se conectam Encrypt=True. Uma conexão com um servidor com um certificado autoassinado ou não confiável falha a menos que você adicione TrustServerCertificate=True (apenas teste ou desenvolvimento) ou instale um certificado confiável. Para um comportamento previsível, defina ambas as palavras-chave explicitamente, por exemplo, Encrypt=True;TrustServerCertificate=False;.

Autenticação do Microsoft Entra ID

1. Usando autenticação de senha (obsoleta pela Microsoft e incompatível com a autenticação multifator (MFA); prefira interativa, principal de serviço ou identidade gerenciada):

   Server=tcp:SERVER.database.windows.net,1433;Initial Catalog=DATABASE_NAME;Authentication=Active Directory Password;User ID=[e-mail];Password=<your-password>;Encrypt=True;

2. Usando a autenticação da entidade de serviço (para robôs não assistidos):

   Server=tcp:SERVER.database.windows.net,1433;Initial Catalog=DATABASE_NAME;Authentication=Active Directory Service Principal;User ID=APP_CLIENT_ID;Password=<your-client-secret>;Encrypt=True;

3. Usando a autenticação de identidade gerenciada (omita User ID para uma identidade atribuída pelo sistema; para uma identidade atribuída pelo usuário, defina-a como o ID do cliente da identidade):

   Server=tcp:SERVER.database.windows.net,1433;Initial Catalog=DATABASE_NAME;Authentication=Active Directory Managed Identity;User ID=USER_ASSIGNED_MI_CLIENT_ID;Encrypt=True;

4. Usando autenticação integrada (usa a Autenticação Integrada do Windows com uma identidade federada do Active Directory local):

   Server=tcp:SERVER.database.windows.net,1433;Initial Catalog=DATABASE_NAME;Authentication=Active Directory Integrated;Encrypt=True;

5. Usando a autenticação interativa (abre um navegador com uma solicitação de MFA; apenas para uso assistido ou de desenvolvimento, não para robôs não assistidos):

   Server=tcp:SERVER.database.windows.net,1433;Initial Catalog=DATABASE_NAME;Authentication=Active Directory Interactive;User ID=[e-mail];Encrypt=True;

Para o driver ODBC, os valores de palavra-chave equivalentes não têm espaços: ActiveDirectoryPassword, ActiveDirectoryServicePrincipal, ActiveDirectoryMsi (identidade gerenciada), ActiveDirectoryIntegrated e ActiveDirectoryInteractive. ActiveDirectoryInteractive está disponível apenas no Windows.

Dica:

Se o mesmo fluxo de trabalho for executado em um robô e em uma máquina de desenvolvimento, Authentication=Active Directory Default. Ela usa DefaultAzureCredential, que tenta variáveis de ambiente, identidade de carga de trabalho e identidade gerenciada antes de recair nas credenciais da ferramenta de desenvolvedor.

Você pode aprender mais sobre a sintaxe da string de conexão na documentação oficial da Microsoft e sobre a autenticação do Microsoft Entra na documentação de autenticação do Microsoft Entra.

Arquivo do Excel

Driver={Microsoft Excel Driver (*.xls, *.xlsx, *.xlsm, *.xlsb)};DBQ=C:\full\path\to\the\sampleFile.xlsx;

Acesso a dados gerenciados do Oracle

Data Source=(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=localhost)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=XEPDB1)));User Id=system;Password=<your-password>;

Você também pode usar o formulário curto do Easy Connect: Data Source=//HOST_NAME:1521/SERVICE_NAME;User Id=USERNAME;Password=<your-password>;.

Para obter mais informações, consulte o Oracle Data Provider para documentação.NET.

Driver Unicode do ODBC 8.3 para SQL

Driver={MySQL ODBC 8.3 Unicode Driver};Server=SERVER_NAME;Database=DATABASE_NAME;User=USERNAME;Password=<your-password>;Option=3;

Você pode aprender mais sobre isso através da página de documentação oficial do MySQL aqui.

Driver SQL ODBC 8.3 ANSI

Driver={MySQL ODBC 8.3 ANSI Driver};Server=SERVER_NAME;Database=DATABASE_NAME;User=USERNAME;Password=<your-password>;Option=3;

Substitua a versão no nome do driver pela versão do MySQL Connector/ODBC instalada na máquina (por exemplo, MySQL ODBC 9.4 Unicode Driver); o nome deve corresponder exatamente ao driver registrado. Prefira o driver Unicode ao invés do driver ANSI para evitar corromper dados não ASCII. O sinalizador Option=3 legado é opcional e não necessário para uso típico.

PostgreSQL

Driver={PostgreSQL Unicode};Server=SERVER_NAME;Port=5432;Database=DATABASE_NAME;Uid=USERNAME;Pwd=<your-password>;

Use a variante ANSI Driver={PostgreSQL ANSI};… apenas para codificações legadas de byte único; prefira o driver Unicode para bancos de dados UTF-8. Adicione sslmode=require; (minúsculas) para impor o TLS.

Importante:

O Driver={...} deve corresponder ao driver registrado na máquina que executa o robô. Dependendo do instalador, o driver psqlODBC de 64 bits é registrado como PostgreSQL Unicode ou PostgreSQL Unicode(x64) (e os equivalentes ANSI). Se o nome não corresponder a um driver registrado, a conexão falhará com "nome da origem de dados não encontrado".

Verifique o nome exato registrado no Administrador de Fonte de Dados ODBC de C:\Windows\System32\odbcad32.exe bits ().

Você pode saber mais consulte a documentação do psqlODBC.

Amazon URL (compatível com MySQL)

O Amazon Amazon MySQL-Compatible Edition usa o protocolo de conexão do MySQL, então você se conecta com o driver do MySQL Connector/ODBC. Aponte Server no ponto de extremidade do cluster (gravador) do Azure:

Driver={MySQL ODBC 9.4 Unicode Driver};Server=CLUSTER.cluster-xxxx.REGION.rds.amazonaws.com;Port=3306;Database=DATABASE_NAME;User=USERNAME;Password=<your-password>;

Banco de dados autônomo Oracle (ATP/ADW) com carteira

Para se conectar ao Oracle Autonomus Database (Processamento de Transações Autônomas ou Warehouse de Dados Autônomo):

1. Baixe o portfólio de instâncias (Wallet_DBNAME.zip) do Oracle Cloud Infrastructure.
2. Extraia todos os arquivos do arquivo da carteira para uma pasta na máquina do robô.
3. Defina a variável de ambiente TNS_ADMIN para essa pasta.
4. Edite o diretório WALLET_LOCATION no sqlnet.ora da carteira para essa mesma pasta. A carteira é enviada com um espaço reservado ?/network/admin que você deve substituir, porque TNS_ADMIN sozinho não é suficiente.

Com a carteira de login automático (cwallet.sso), nenhuma senha da carteira é necessária. Caso contrário, forneça a senha da carteira para que o driver possa abrir o ewallet.p12 protegido por senha.

Em seguida, use um alias de serviço de tnsnames.ora (DBNAME_high, DBNAME_medium ou DBNAME_low, mais DBNAME_tp e DBNAME_tpurgent em bancos de dados de processamento de transações):

Data Source=DBNAME_low;User Id=USERNAME;Password=<your-password>;

Dica:

Você também pode conectar-se sem uma carteira usando o TLS unidirecional, desde que a instância do Banco de Dados Autônomo esteja configurada para permitir conexões TLS. As instâncias configuradas para TLS mutuamente (mTLS) ainda exigem a carteira.

Você pode saber mais consulte a documentação de configuração do Oracle ODP.NET.

Microsoft Access

Uso do driver ODBC:

Driver={Microsoft Access Driver (*.mdb, *.accdb)};Dbq=C:\full\path\to\database.accdb;Uid=Admin;Pwd=;

Usando o provedor OLE DB (, disponível System.Data.OleDb no Windows):

Provider=Microsoft.ACE.OLEDB.12.0;Data Source=C:\full\path\to\database.accdb;Persist Security Info=False;

Para um arquivo protegido por senha, acrescente Jet OLEDB:Database Password=<your-password>; à string OLE DB.

Importante:

Tanto o driver ODBC quanto o provedor ACE OLE DB vêm do redistribuível do Mecanismo de Banco de Dados do Microsoft Access, cuja arquitetura (x86 ou x64) deve corresponder à arquitetura do robô e do projeto. Uma incompatibilidade resulta em um erro “provedor não registrado na máquina local” erro.

SAP HANA

Driver={HDBODBC};ServerNode=HOST_NAME:3NN15;UID=USERNAME;PWD=<your-password>;

HDBODBC para robôs de 64 bits (HDBODBC32 apenas para um processo de 32 bits). Para um banco de dados de contêiner único ou o primeiro tenant, a porta é 3NN15, onde NN é o número da instância de dois dígitos — por exemplo, 30015 para a instância 00 ou 30515 para a instância 05.

Para um sistema de contêiner de banco de dados multitenant (MDC), conecte-se por meio da porta de banco de dados do sistema 3NN13 e nomeie o tenant, que é o formulário que a SAP recomenda:

Driver={HDBODBC};ServerNode=HOST_NAME:30013;DATABASENAME=TENANT_DB;UID=USERNAME;PWD=<your-password>;

Importante:

Para SAP HANA Cloud (em contrário ao SAP HANA local), o host é um endpoint no estilo UUID na porta 443, e a conexão é sempre criptografada. Defina encrypt=TRUE explicitamente para cliente SAP HANA 2.5 e anterior; os clientes mais recentes o inferem na porta 443. O esquema de portas 3NN15 aplica-se apenas a sistemas locais.

IBM Db2

Driver={IBM DB2 ODBC DRIVER};Database=DATABASE_NAME;Hostname=HOST_NAME;Port=50000;Protocol=TCPIP;Uid=USERNAME;Pwd=<your-password>;

O nome do driver registrado pode ser específico da instalação — com várias cópias do Db2, pode ser IBM DB2 ODBC DRIVER - DB2COPY1 Verifique o nome exato no Administrador da Fonte de Dados ODBC no Windows ou em odbcinst.ini no Linux. A porta 50000 é o padrão comum, mas a porta real é definida por instância por SVCENAME.

SQLite

As atividades Database usam Microsoft.Data.Sqlite Forneça o caminho para o arquivo de banco de dados:

Data Source=C:\full\path\to\database.db;

As palavras-chave opcionais incluem Mode=ReadOnly (ou ReadWrite / ReadWriteCreate), Foreign Keys=True para impor a integridade referencial e Cache=Shared. A palavra-chave Version=3 não é válida aqui — ela pertence ao provedor System.Data.SQLite mais antigo e resulta em um erro.

Você pode saber mais na documentação do Microsoft.Data.Sqliter.

JDBC

As atividades Database são executadas no.NET e não usam drivers JDBC diretamente. Para alcançar um banco de dados que você normalmente acessaria por meio do JDBC, use o driver ODBC com a string de conexão ODBC para esse banco de dados neste guia ou implemente a conexão em um fluxo de trabalho codificado usando o driver.NET ou ADO.NET do fornecedor do banco de dados.

Solução de problemas de conexão comuns

Nome da origem de dados não encontrado (erro IM002)

ERROR [IM002] [Microsoft][ODBC Driver Manager] Data source name not found, and no default driver specified

O driver ODBC nomeado em Driver={...} não está instalado ou está registrado com outro nome ou arquitetura. Para corrigi-lo:

1. Instale o driver ODBC correspondente.
2. Confirme se aparece no Administrador de Fonte de Dados ODBC que corresponde à arquitetura do robô. Há administradores separados de 32 bits e 64 bits.
3. Copie o nome exato do driver do administrador para Driver={...}. O nome é muitas vezes específico da versão ou da instalação (por exemplo, PostgreSQL Unicode(x64), MySQL ODBC 9.4 Unicode Driver ou IBM DB2 ODBC DRIVER - DB2COPY1).

Não foi possível carregar o driver (erro IM003)

ERROR [IM003] Specified driver could not be loaded due to system error 1114

O erro do sistema 1114 significa que a biblioteca do driver foi encontrada, mas sua rotina de inicialização falhou — normalmente uma dependência ausente (como um runtime necessário) ou uma incompatibilidade de arquitetura ou versão. É comum com o Oracle Instant Client (SQORA32.dll) e o IBM Db2 (DB2CLIO.DLL). Para corrigi-lo:

1. Certifique-se de que a arquitetura do driver corresponda ao runtime.
2. Instale quaisquer pré-requisitos que o driver exigir.
3. Reinstale ou atualize o driver.

Arquitetura de driver e suporte à plataforma

Instale o driver do banco de dados que corresponda à arquitetura de runtime do projeto. Os projetos do Windows são executados como processos de 64 bits e precisam do driver ODBC ou OLE DB de 64 bits. Os projetos do Windows - Legado são executados como processos de 32 bits e precisam do driver de 32 bits.

OLE DB (,System.Data.OleDb para Access e Excel) está disponível apenas no Windows. O ODBC funciona no Windows e em robôs Linux ou macOS quando o unixODBC 2.3.1 ou posterior e o driver de destino estão instalados nessa máquina.

Dica:

Após instalar um driver, reinicie o Studio ou o robô para que ele detecte o driver.