# Conceitos básicos do driver JDBC 3.x
<a name="jdbc-v3-driver-getting-started"></a>

Use as informações desta seção para começar a usar o driver JDBC 3.x do Amazon Athena.

**Topics**
+ [Instruções de instalação](#jdbc-v3-driver-installation-instructions)
+ [Executar o driver](#jdbc-v3-driver-running-the-driver)
+ [Configurar o driver](#jdbc-v3-driver-configuring-the-driver)
+ [Atualizar o driver Athena JDBC v2](#jdbc-v3-driver-upgrading-from-the-athena-jdbc-v2-driver-to-v3)

## Instruções de instalação
<a name="jdbc-v3-driver-installation-instructions"></a>

Você pode usar o driver JDBC 3.x em uma aplicação personalizada ou em um cliente SQL de terceiros.

### Em uma aplicação personalizada
<a name="jdbc-v3-driver-installation-in-a-custom-application"></a>

Baixe o arquivo `.zip` que contém o jar do driver e suas dependências. Cada dependência tem seu próprio arquivo `.jar`. Adicione o jar do driver como uma dependência na sua aplicação personalizada. Adicione seletivamente as dependências do jar do driver, com base em você já ter ou não adicionado essas dependências à aplicação de outra fonte.

### Em um cliente SQL de terceiros
<a name="jdbc-v3-driver-installation-in-a-third-party-sql-client"></a>

Baixe o arquivo jar com dependências do driver e adicione-o ao cliente SQL de terceiros seguindo as instruções para esse cliente.

## Executar o driver
<a name="jdbc-v3-driver-running-the-driver"></a>

Para executar o driver, você pode usar uma aplicação personalizada ou um cliente SQL de terceiros.

### Em uma aplicação personalizada
<a name="jdbc-v3-driver-running-in-a-custom-application"></a>

Use a interface JDBC para interagir com o driver JDBC em um programa. O código a seguir mostra um exemplo de aplicação Java personalizada.

```
public static void main(String args[]) throws SQLException {
    Properties connectionParameters = new Properties();
    connectionParameters.setProperty("Workgroup", "primary");
    connectionParameters.setProperty("Region", "us-east-2");
    connectionParameters.setProperty("Catalog", "AwsDataCatalog");
    connectionParameters.setProperty("Database","sampledatabase");
    connectionParameters.setProperty("OutputLocation","s3://amzn-s3-demo-bucket");
    connectionParameters.setProperty("CredentialsProvider","DefaultChain");
    String url = "jdbc:athena://";
    AthenaDriver driver = new AthenaDriver();
    Connection connection = driver.connect(url, connectionParameters);
    Statement statement = connection.createStatement();
    String query = "SELECT * from sample_table LIMIT 10";
    ResultSet resultSet = statement.executeQuery(query);
    printResults(resultSet); // A custom-defined method for iterating over a
                             // result set and printing its contents
}
```

### Em um cliente SQL de terceiros
<a name="jdbc-v3-driver-running-in-a-third-party-sql-client"></a>

Siga a documentação do cliente SQL que você está usando. Normalmente, você usa a interface gráfica do usuário do cliente SQL para inserir e enviar a consulta, e os resultados da consulta são exibidos na mesma interface.

## Configurar o driver
<a name="jdbc-v3-driver-configuring-the-driver"></a>

Você pode usar os parâmetros de conexão para configurar o driver JDBC do Amazon Athena. Para obter os parâmetros de conexão compatíveis, consulte [Parâmetros de conexão do JDBC 3.x do Amazon Athena](jdbc-v3-driver-connection-parameters.md).

### Em uma aplicação personalizada
<a name="jdbc-v3-driver-configuring-in-a-custom-application"></a>

Para definir os parâmetros de conexão do driver JDBC em uma aplicação personalizada, faça um dos seguintes procedimentos:
+ Adicione os nomes dos parâmetros e seus valores a um objeto `Properties`. Quando você chamar `Connection#connect`, passe esse objeto junto com a URL. Para obter um exemplo, consulte o exemplo de aplicação Java em [Executar o driver](#jdbc-v3-driver-running-the-driver).
+ Na string de conexão (a URL), use o formato a seguir para adicionar os nomes dos parâmetros e seus valores diretamente após o prefixo do protocolo.

  ```
  {{<parameterName>}}={{<parameterValue>}};
  ```

  Use um ponto e vírgula no final de cada par nome/valor do parâmetro e não deixe espaço em branco após o ponto e vírgula, como no exemplo a seguir.

  ```
  String url = "jdbc:athena://WorkGroup=primary;Region=us-east-1;...;";AthenaDriver driver = new AthenaDriver();Connection connection = driver.connect(url, null);
  ```
**nota**  
Se um parâmetro for especificado tanto na string de conexão quanto no objeto `Properties`, o valor na string de conexão terá precedência. Não é recomendável especificar o mesmo parâmetro em ambos os lugares.
+ Adicione os valores dos parâmetros como argumentos aos métodos de `AthenaDataSource`, como no exemplo a seguir.

  ```
  AthenaDataSource dataSource = new AthenaDataSource();
      dataSource.setWorkGroup("primary");
      dataSource.setRegion("us-east-2");
      ...
      Connection connection = dataSource.getConnection();
      ...
  ```

### Em um cliente SQL de terceiros
<a name="jdbc-v3-driver-configuring-in-a-third-party-sql-client"></a>

Siga as instruções do cliente SQL que você estiver usando. Normalmente, o cliente fornece uma interface gráfica de usuário para inserir os nomes dos parâmetros e seus valores.

## Atualizar o driver Athena JDBC v2
<a name="jdbc-v3-driver-upgrading-from-the-athena-jdbc-v2-driver-to-v3"></a>

A maioria dos parâmetros de conexão do JDBC versão 3 é compatível retroativamente com o driver JDBC versão 2 (Simba). Isso significa que uma string de conexão da versão 2 pode ser reutilizada com a versão 3 do driver. Porém, alguns parâmetros de conexão foram alterados. Essas mudanças estão descritas aqui. Ao atualizar para o driver JDBC versão 3, atualize a configuração existente, se for o caso.

### Classe do driver
<a name="jdbc-v3-driver-upgrading-driver-class"></a>

Algumas ferramentas de BI solicitam que você forneça a classe do driver, encontrada no arquivo `.jar` do driver JDBC. A maioria das ferramentas encontra essa classe automaticamente. O nome totalmente qualificado da classe no driver da versão 3 é `com.amazon.athena.jdbc.AthenaDriver`. No driver da versão 2, a classe era `com.simba.athena.jdbc.Driver`.

### String de conexão
<a name="jdbc-v3-driver-upgrading-connection-string"></a>

O driver da versão 3 usa `jdbc:athena://` como protocolo no início do URL da string de conexão do JDBC. O driver da versão 3 também é compatível com o protocolo `jdbc:awsathena://` da versão 2, mas o uso do protocolo da versão 2 foi descontinuado. Para evitar comportamentos indefinidos, a versão 3 não aceita strings de conexão que comecem com `jdbc:awsathena://` se a versão 2 (ou qualquer outro driver que aceite strings de conexão que comecem com `jdbc:awsathena://`) tiver sido registrada com a classe [DriverManager](https://docs.oracle.com/javase/8/docs/api/java/sql/DriverManager.html).

### Provedores de credenciais
<a name="jdbc-v3-driver-upgrading-credentials-providers"></a>

O driver da versão 2 usa nomes totalmente qualificados para identificar os diferentes provedores de credenciais (por exemplo, `com.simba.athena.amazonaws.auth.DefaultAWSCredentialsProviderChain`). O driver da versão 3 usa nomes mais curtos (por exemplo, `DefaultChain`). Os novos nomes são descritos nas seções correspondentes para cada provedor de credenciais.

[Os provedores de credenciais personalizadas escritos para o driver da versão 2 precisam ser modificados para que o driver da versão 3 implemente a interface [AWSCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/AwsCredentialsProvider.html) a partir do novo AWS SDK para Java em vez da interface AWSCredentialsProvider](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/AWSCredentialsProvider.html) a partir do AWS SDK para Java anterior.

`PropertiesFileCredentialsProvider` não é suportado no driver JDBC 3.x. O provedor foi usado no driver JDBC 2.x, mas pertence à versão anterior do AWS SDK para Java, que está chegando ao fim do suporte. Para obter a mesma funcionalidade no driver JDBC 3.x, use o provedor [Credenciais do perfil de configuração da AWS](jdbc-v3-driver-aws-configuration-profile-credentials.md).

### Nível de log
<a name="jdbc-v3-driver-upgrading-log-level"></a>

A tabela a seguir mostra as diferenças nos parâmetros de `LogLevel` dos drivers JDBC versão 2 e versão 3.


****  

| Versão do driver JDBC | Nome do parâmetro | Tipo de parâmetro | Valor padrão | Possíveis valores | Exemplo de string de conexão | 
| --- | --- | --- | --- | --- | --- | 
| v2 | LogLevel | Opcional | 0 | 0-6 | LogLevel=6; | 
| v3 | LogLevel | Opcional | TRACE | OFF, ERROR, WARN, INFO, DEBUG, TRACE | LogLevel=INFO; | 

### Recuperação da ID da consulta
<a name="jdbc-v3-driver-upgrading-query-id-retrieval"></a>

No driver da versão 2, você desempacota uma instância de `Statement` em `com.interfaces.core.IStatementQueryInfoProvider`, uma interface que tem dois métodos: `#getPReparedQueryId` e `#getQueryId`. Você pode usar esses métodos para obter o ID de execução da consulta que foi executada.

No driver da versão 3, você desempacota as instâncias `Statement`, `PreparedStatement` e `ResultSet` na interface `com.amazon.athena.jdbc.AthenaResultSet`. A interface tem um método: `#getQueryExecutionId`.