# Introducción al controlador JDBC 3.x
<a name="jdbc-v3-driver-getting-started"></a>

Utilice la información de esta sección para empezar a usar el controlador JDBC 3.x de Amazon Athena.

**Topics**
+ [Instrucciones de instalación](#jdbc-v3-driver-installation-instructions)
+ [Ejecución del controlador](#jdbc-v3-driver-running-the-driver)
+ [Configuración del controlador](#jdbc-v3-driver-configuring-the-driver)
+ [Actualización desde el controlador Athena JDBC v2](#jdbc-v3-driver-upgrading-from-the-athena-jdbc-v2-driver-to-v3)

## Instrucciones de instalación
<a name="jdbc-v3-driver-installation-instructions"></a>

Puede utilizar el controlador JDBC 3.x en una aplicación personalizada o desde un cliente SQL de terceros.

### En una aplicación personalizada
<a name="jdbc-v3-driver-installation-in-a-custom-application"></a>

Descargue el archivo `.zip` que contiene el archivo jar del controlador y sus dependencias. Cada dependencia tiene su propio archivo `.jar`. Agregue el archivo jar del controlador como una dependencia en la aplicación personalizada. Agregue de forma selectiva las dependencias del contenedor de controladores en función de si ya las ha agregado a su aplicación desde otra fuente.

### En un cliente SQL de terceros
<a name="jdbc-v3-driver-installation-in-a-third-party-sql-client"></a>

Descargue el archivo uber jar del controlador y agréguelo al cliente SQL de terceros siguiendo las instrucciones de ese cliente.

## Ejecución del controlador
<a name="jdbc-v3-driver-running-the-driver"></a>

Para ejecutar el controlador, puede utilizar una aplicación personalizada o un cliente SQL de terceros.

### En una aplicación personalizada
<a name="jdbc-v3-driver-running-in-a-custom-application"></a>

Utilice la interfaz de JDBC para interactuar con el controlador JDBC desde un programa. El siguiente código muestra un ejemplo de aplicación 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
}
```

### En un cliente SQL de terceros
<a name="jdbc-v3-driver-running-in-a-third-party-sql-client"></a>

Siga la documentación del cliente SQL que esté utilizando. Normalmente, se utiliza la interfaz gráfica de usuario del cliente SQL para introducir y enviar la consulta, y los resultados de la consulta se muestran en la misma interfaz.

## Configuración del controlador
<a name="jdbc-v3-driver-configuring-the-driver"></a>

Puede usar los parámetros de conexión para configurar el controlador JDBC de Amazon Athena. Para obtener información sobre los parámetros de conexión compatibles, consulte [Parámetros de conexión JDBC 3.x de Amazon Athena](jdbc-v3-driver-connection-parameters.md).

### En una aplicación personalizada
<a name="jdbc-v3-driver-configuring-in-a-custom-application"></a>

Para configurar los parámetros de conexión del controlador JDBC en una aplicación personalizada, realice una de las siguientes acciones:
+ Añada los nombres de los parámetros y sus valores a un objeto `Properties`. Cuando llame a `Connection#connect`, pase ese objeto junto con la URL. Por ejemplo, consulte la aplicación de muestra Java en [Ejecución del controlador](#jdbc-v3-driver-running-the-driver).
+ En la cadena de conexión (la URL), utilice el siguiente formato para añadir los nombres de los parámetros y sus valores directamente después del prefijo del protocolo.

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

  Utilice un punto y coma al final de cada par de nombre y valor de parámetro y no deje ningún espacio en blanco después del punto y coma, como en el siguiente ejemplo.

  ```
  String url = "jdbc:athena://WorkGroup=primary;Region=us-east-1;...;";AthenaDriver driver = new AthenaDriver();Connection connection = driver.connect(url, null);
  ```
**nota**  
Si se especifica un parámetro tanto en la cadena de conexión como en el objeto `Properties`, el valor de la cadena de conexión tiene prioridad. No se recomienda especificar el mismo parámetro en ambos lugares.
+ Agregue los valores de los parámetros como argumentos a los métodos de `AthenaDataSource`, como en el siguiente ejemplo.

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

### En un cliente SQL de terceros
<a name="jdbc-v3-driver-configuring-in-a-third-party-sql-client"></a>

Siga las instrucciones del cliente SQL que esté utilizando. Normalmente, el cliente proporciona una interfaz gráfica de usuario para introducir los nombres de los parámetros y sus valores.

## Actualización desde el controlador Athena JDBC v2
<a name="jdbc-v3-driver-upgrading-from-the-athena-jdbc-v2-driver-to-v3"></a>

La mayoría de los parámetros de conexión de la versión 3 de JDBC son compatibles con versiones anteriores de la versión 2 (Simba) del controlador JDBC. Esto significa que una cadena de conexión de la versión 2 se puede reutilizar con la versión 3 del controlador. Sin embargo, algunos parámetros de conexión han cambiado. Estos cambios se describen aquí. Cuando actualice a la versión 3 del controlador JDBC, actualice la configuración existente si es necesario.

### Clase de controlador
<a name="jdbc-v3-driver-upgrading-driver-class"></a>

Algunas herramientas de BI le piden que proporcione la clase de controlador del archivo del controlador JDBC `.jar`. La mayoría de las herramientas encuentran esta clase automáticamente. El nombre completo de la clase en el controlador de la versión 3 es `com.amazon.athena.jdbc.AthenaDriver`. En el controlador de la versión 2, la clase era `com.simba.athena.jdbc.Driver`.

### Cadena de conexión
<a name="jdbc-v3-driver-upgrading-connection-string"></a>

El controlador de la versión 3 utiliza `jdbc:athena://` para el protocolo al principio de la URL de la cadena de conexión de JDBC. El controlador de la versión 3 también es compatible con el protocolo de la versión 2 de `jdbc:awsathena://`; sin embargo, el uso del protocolo de la versión 2 está obsoleto. Para evitar comportamientos indefinidos, la versión 3 no acepta cadenas de conexión que comiencen con `jdbc:awsathena://` si la versión 2 (o cualquier otro controlador que acepte cadenas de conexión que comiencen con `jdbc:awsathena://`) se registró en la clase [DriverManager](https://docs.oracle.com/javase/8/docs/api/java/sql/DriverManager.html).

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

El controlador de la versión 2 utiliza nombres totalmente cualificados para identificar a los distintos proveedores de credenciales (por ejemplo, `com.simba.athena.amazonaws.auth.DefaultAWSCredentialsProviderChain`. El controlador de la versión 3 utiliza nombres más cortos (por ejemplo, `DefaultChain`). Los nuevos nombres se describen en las secciones correspondientes de cada proveedor de credenciales.

Los proveedores de credenciales personalizadas escritos para la versión 2 del controlador deben modificarse para que la versión 3 del controlador implemente la interfaz [AwsCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/AwsCredentialsProvider.html) desde el nuevo AWS SDK para Java en lugar de la interfaz [AWSCredentialsProvider](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/AWSCredentialsProvider.html) del AWS SDK para Java anterior.

El `PropertiesFileCredentialsProvider` no es compatible con el controlador JDBC 3.x. El proveedor se utilizó en el controlador JDBC 2.x, pero pertenece a la versión anterior del AWS SDK para Java, que está a punto de finalizar su período de soporte. Para lograr la misma funcionalidad en el controlador JDBC 3.x, utilice el proveedor [Credenciales del perfil de configuración AWS](jdbc-v3-driver-aws-configuration-profile-credentials.md) en su lugar.

### Nivel de registro
<a name="jdbc-v3-driver-upgrading-log-level"></a>

En la siguiente tabla se muestran las diferencias en los parámetros `LogLevel` de los controladores JDBC de la versión 2 y la versión 3.


****  

| Versión del controlador JDBC | Nombre del parámetro | Tipo de parámetro | Predeterminado | Valores posibles | Ejemplo de la cadena de conexión | 
| --- | --- | --- | --- | --- | --- | 
| v2 | LogLevel | Opcional | 0 | De 0 a 6 | LogLevel=6; | 
| v3 | LogLevel | Opcional | SEGUIMIENTO | DESACTIVADO, ERROR, ADVERTENCIA, INFORMACIÓN, DEPURACIÓN, RASTREO | LogLevel=INFO; | 

### Recuperación del ID de consulta
<a name="jdbc-v3-driver-upgrading-query-id-retrieval"></a>

En el controlador de la versión 2, se desempaqueta una instancia `Statement` en `com.interfaces.core.IStatementQueryInfoProvider`, que es una interfaz que tiene dos métodos: `#getPReparedQueryId` y `#getQueryId`. Puedes usar estos métodos para obtener el identificador de ejecución de una consulta que se ha ejecutado.

En el controlador de la versión 3, desempaquete las instancias `Statement`, `PreparedStatement`, y `ResultSet` en la interfaz `com.amazon.athena.jdbc.AthenaResultSet`. La interfaz tiene un método: `#getQueryExecutionId`.