PolarDB:JDBC

Requisitos previos

• Creó una cuenta de base de datos en el clúster de PolarDB. Para obtener más información, consulte Create a database account.

• Agregó las direcciones IP de los hosts que necesitan acceder al clúster de PolarDB a una lista de permitidos. Para obtener más información, consulte Set a cluster whitelist.

Contexto

El controlador JDBC para PolarDB for PostgreSQL (Compatible with Oracle) se basa en el controlador JDBC de PostgreSQL de código abierto. Utiliza el protocolo de red nativo de PostgreSQL, lo que permite que los programas Java se conecten a la base de datos con código Java estándar e independiente de la base de datos.

El controlador JDBC usa el protocolo PostgreSQL 3.0 y es compatible con Java 6 (JDBC 4.0), Java 7 (JDBC 4.1) y Java 8 (JDBC 4.2).

Configure el controlador JDBC

Para usar el controlador JDBC en una aplicación Java, agregue la ruta de su archivo JAR a su CLASSPATH. Por ejemplo, si el archivo JAR se almacena en el directorio /usr/local/polardb/share/java/, ejecute a continuación el comando para agregar su ruta al CLASSPATH:

export CLASSPATH=$CLASSPATH:/usr/local/polardb/share/java/<jar-file-name.jar>

Ejemplo:

export CLASSPATH=$CLASSPATH:/usr/local/polardb/share/java/polardb-jdbc18.jar

Para comprobar la versión de su controlador JDBC, ejecute a continuación el comando:

#java -jar <jar-file-name.jar>

Ejemplo:

#java -jar polardb-jdbc18.jar
POLARDB JDBC Driver 42.2.XX.XX.0

Conéctese a PolarDB

• Example

  package com.aliyun.polardb;
  
  import java.sql.Connection;
  import java.sql.Driver;
  import java.sql.DriverManager;
  import java.sql.ResultSet;
  import java.sql.SQLException;
  import java.sql.Statement;
  import java.util.Properties;
  
  /**
   * POLARDB JDBC DEMO
   * <p>
   * Make sure the IP address of the host running this demo is in your cluster's whitelist.
   */
  public class PolarDBJdbcDemo {
    /**
     * Replace the following placeholder values.
     */
    private final String host = "***.o.polardb.rds.aliyuncs.com";
    private final String user = "***";
    private final String password = "***";
    private final String port = "1521";
    private final String database = "db_name";
  
    public void run() throws Exception {
      Connection connect = null;
      Statement statement = null;
      ResultSet resultSet = null;
  
      try {
        Class.forName("com.aliyun.polardb.Driver");
  
        Properties props = new Properties();
        props.put("user", user);
        props.put("password", password);
        String url = "jdbc:polardb://" + host + ":" + port + "/" + database;
        connect = DriverManager.getConnection(url, props);
  
        /**
         * create table foo(id int, name varchar(20));
         */
        String sql = "select id, name from foo";
        statement = connect.createStatement();
        resultSet = statement.executeQuery(sql);
        while (resultSet.next()) {
          System.out.println("id:" + resultSet.getInt(1));
          System.out.println("name:" + resultSet.getString(2));
        }
      } catch (Exception e) {
        e.printStackTrace();
        throw e;
      } finally {
        try {
          if (resultSet != null)
            resultSet.close();
          if (statement != null)
            statement.close();
          if (connect != null)
            connect.close();
        } catch (SQLException e) {
          e.printStackTrace();
          throw e;
        }
      }
    }
  
    public static void main(String[] args) throws Exception {
      PolarDBJdbcDemo demo = new PolarDBJdbcDemo();
      demo.run();
    }
  }

• Cargue el controlador JDBC

  Ejecute a continuación el comando en su aplicación para cargar el controlador JDBC:

  Class.forName("com.aliyun.polardb.Driver");

• Conéctese a la base de datos

  En JDBC, una URL de conexión representa la conexión a la base de datos. Por ejemplo:

  jdbc:polardb://pc-***.o.polardb.rds.aliyuncs.com:1521/polardb_test?user=test&password=Pw123456

  Parámetro	Ejemplo	Descripción
  Prefijo de URL	jdbc:polardb://	El prefijo de URL para conectarse a PolarDB siempre es jdbc:polardb://.
  Endpoint	pc-***.o.polardb.rds.aliyuncs.com	El endpoint del clúster de PolarDB. Para obtener más información, consulte View or apply for an endpoint.
  Puerto	1521	El puerto del clúster de PolarDB. El valor predeterminado es 1521.
  Base de datos	polardb_test	El nombre de la base de datos a la que desea conectarse.
  Nombre de usuario	test	El nombre de usuario del clúster de PolarDB.
  Contraseña	Pw123456	La contraseña del nombre de usuario del clúster de PolarDB.

• Consulte datos y procese los resultados

  Para ejecutar una consulta, cree un objeto Statement, PreparedStatement o CallableStatement.

  El ejemplo anterior utiliza un objeto Statement. A continuación se muestra cómo usar un objeto PreparedStatement:

  PreparedStatement st = conn.prepareStatement("select id, name from foo where id > ?");
  st.setInt(1, 10);
  resultSet = st.executeQuery();
  while (resultSet.next()) {
      System.out.println("id:" + resultSet.getInt(1));
      System.out.println("name:" + resultSet.getString(2));
  }

  Un objeto CallableStatement sirve para llamar a un procedimiento almacenado. A continuación se muestra un ejemplo:

  String sql = "{?=call getName (?, ?, ?)}";
  CallableStatement stmt = conn.prepareCall(sql);
  stmt.registerOutParameter(1, java.sql.Types.INTEGER);
  
  //Bind IN parameter first, then bind OUT parameter
  int id = 100;
  stmt.setInt(2, id); // This would set ID as 102
  stmt.registerOutParameter(3, java.sql.Types.VARCHAR);
  stmt.registerOutParameter(4, java.sql.Types.INTEGER);
  
  //Use execute method to run stored procedure.
  stmt.execute();
  
  //Retrieve name with getXXX method
  String name = stmt.getString(3);
  Integer msgId = stmt.getInt(4);
  Integer result = stmt.getInt(1);
  System.out.println("Name with ID:" + id + " is " + name + ", and messageID is " + msgId + ", and return is " + result);

  El procedimiento almacenado getName que se usó en el código anterior se define de la siguiente manera:

  CREATE OR REPLACE FUNCTION getName(
      id        In      Integer,
      name      Out     Varchar2,
      result    Out     Integer
    ) Return Integer
  Is
    ret     Int;
  Begin
    ret := 0;
    name := 'Test';
    result := 1;
    Return(ret);
  End;

  Nota

  En los procedimientos almacenados que devuelven un cursor, el tipo de cursor depende de la versión de Java:

  • Para Java 8 o versiones posteriores, use Types.REF_CURSOR.

  • Para versiones anteriores a Java 8, use Types.REF.

• Establezca el tamaño de extracción

  De forma predeterminada, el controlador extrae todos los resultados de la consulta de la base de datos al mismo tiempo. En conjuntos de resultados grandes, esto consume mucha memoria del cliente y puede provocar un error de falta de memoria (OOM). Para evitarlo, JDBC proporciona un ResultSet basado en cursores que extrae los datos por lotes. Para usar esta función, debe:

  • Establecer FetchSize. El valor predeterminado de FetchSize es 0, lo que significa que todos los datos se extraen al mismo tiempo.

  • Establecer la propiedad autoCommit de la conexión en false.

  // make sure autocommit is off
  conn.setAutoCommit(false);
  Statement st = conn.createStatement();
  
  // Set fetchSize to use a cursor
  st.setFetchSize(50);
  ResultSet rs = st.executeQuery("SELECT * FROM mytable");
  while (rs.next())
  {
      System.out.print("a row was returned.");
  }
  rs.close();
  
  // Reset fetchSize to turn off the cursor
  st.setFetchSize(0);
  rs = st.executeQuery("SELECT * FROM mytable");
  while (rs.next())
  {
      System.out.print("many rows were returned.");
  }
  rs.close();
  
  // Close the statement.
  st.close();

Integración con Maven

Si su proyecto Java se compila con Maven, ejecute a continuación el comando para instalar el paquete del controlador JDBC de PolarDB en su repositorio local:

mvn install:install-file -DgroupId=com.aliyun -DartifactId=<jar-file-name> -Dversion=1.1.2 -Dpackaging=jar -Dfile=/usr/local/polardb/share/java/<jar-file-name.jar>

Ejemplo:

mvn install:install-file -DgroupId=com.aliyun -DartifactId=polardb-jdbc18 -Dversion=1.1.2 -Dpackaging=jar -Dfile=/usr/local/polardb/share/java/polardb-jdbc18.jar

Agregue a continuación la dependencia al archivo pom.xml de su proyecto de Maven.

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId><jar-file-name></artifactId>
    <version>1.1.2</version>
</dependency>

Ejemplo:

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>polardb-jdbc18</artifactId>
    <version>1.1.2</version>
</dependency>

Integración con Hibernate

Si su proyecto usa Hibernate, configure la clase del controlador y el dialecto para PolarDB en su archivo hibernate.cfg.xml.

<property name="connection.driver_class">com.aliyun.polardb.Driver</property>
<property name="connection.url">jdbc:polardb://pc-***.o.polardb.rds.aliyuncs.com:1521/polardb_test</property>
<property name="dialect">org.hibernate.dialect.PostgresPlusDialect</property>

Integración con Druid

• De forma predeterminada, Druid 1.1.24 y las versiones posteriores admiten el controlador de PolarDB. No necesita establecer los parámetros driverClassName ni dbtype.

• En versiones anteriores a Druid 1.1.24, debe establecer explícitamente los parámetros driverClassName y dbtype:

  dataSource.setDriverClassName("com.aliyun.polardb.Driver");
  dataSource.setDbType("postgresql");

  Nota

  Las versiones de Druid anteriores a la 1.1.24 no admiten de forma nativa PolarDB. Por lo tanto, debe establecer el parámetro dbtype en postgresql.

Si necesita aplicar cifrado a la contraseña de la base de datos en el pool de conexiones de Druid, consulte Cifrado de contraseñas de bases de datos.

Integración con Activiti

Si su aplicación usa el framework Activiti para gestionar procesos de negocio, podría presentarse a continuación el error cuando inicialice un origen de datos de PolarDB.

couldn't deduct database type from database product name 'POLARDB Database Compatible with Oracle'

Este error ocurre porque la asignación integrada de Activiti entre nombres de productos de bases de datos y tipos de bases de datos no incluye una entrada para PolarDB. Para resolverlo, cree una subclase de SpringProcessEngineConfiguration y sobrescriba el método buildProcessEngine para especificar explícitamente el tipo de base de datos. A continuación se muestra un ejemplo de código.

package com.aliyun.polardb;

import org.activiti.engine.ProcessEngine;
import org.activiti.spring.SpringProcessEngineConfiguration;

public class PolarDBSpringProcessEngineConfiguration extends SpringProcessEngineConfiguration {

    public PolarDBSpringProcessEngineConfiguration() {
        super();
    }

    @Override
    public ProcessEngine buildProcessEngine() {
        setDatabaseType(DATABASE_TYPE_POSTGRES);
        return super.buildProcessEngine();
    }
}

Coloque la subclase de SpringProcessEngineConfiguration en su proyecto. Después, en el archivo de configuración, establezca que el motor cargue la configuración desde esta clase durante la inicialización. A continuación se muestra un ejemplo de código.

<bean id="processEngineConfiguration" class="com.aliyun.polardb.PolarDBSpringProcessEngineConfiguration">
      <property name="dataSource" ref="dataSource"/>
      <property name="transactionManager" ref="transactionManager"/>
      <property name="databaseSchemaUpdate" value="true"/>
      <!-- Other configurations are omitted here. -->
</bean>

Integración con Quartz

org.quartz.jobStore.driverDelegateClass = org.quartz.impl.jdbcjobstore.PostgreSQLDelegate

Integración con WebSphere

Integración con MyBatis

Cuando use MyBatis, es posible que necesite configurar un databaseIdProvider. A continuación se muestra la configuración predeterminada:

<databaseIdProvider type="DB_VENDOR">
  <property name="SQL Server" value="sqlserver"/>
  <property name="DB2" value="db2"/>
  <property name="Oracle" value="oracle" />
</databaseIdProvider>

Un databaseIdProvider proporciona una asignación de un nombre de producto de base de datos a un alias específico, que es el databaseId. Esto garantiza que un nombre de producto de base de datos se asigne al mismo alias incluso si el nombre del producto cambia entre distintas versiones de la base de datos.

En un archivo de asignación XML de MyBatis, agregue el atributo databaseId a una instrucción SQL. De este modo, la instrucción se ejecuta únicamente en la base de datos que coincida con ese databaseId. Cuando MyBatis carga el archivo de asignación, solo carga las instrucciones con un databaseId coincidente y todas aquellas que no tengan el atributo databaseId.

  <property name="POLARDB" value="polardb" />

Preguntas frecuentes

• P: ¿Cómo selecciono un controlador JDBC? ¿Puedo usar un controlador de la comunidad de código abierto?

  R: PolarDB for PostgreSQL (Compatible with Oracle) se basa en PostgreSQL de código abierto, pero algunas de sus funciones requieren compatibilidad a nivel de controlador. Por lo tanto, se recomienda usar el controlador JDBC oficial de PolarDB, el cual puede descargar desde la página oficial de descarga de controladores.

• P: ¿El controlador JDBC de PolarDB está disponible en los repositorios públicos de Maven?

  R: No. El controlador no está disponible en los repositorios públicos de Maven. Debe descargar el archivo JAR desde el sitio web oficial y, en proyectos de Maven, instalarlo manualmente en su repositorio local.

• P: ¿Cómo compruebo el número de versión del controlador?

  R: Ejecute el comando java -jar <driver-name> para consultar el número de versión.

• P: ¿La URL de conexión admite varias direcciones IP y puertos?

  R: Sí. El controlador JDBC de PolarDB for PostgreSQL (Compatible with Oracle) le permite especificar varios pares de host y puerto en la URL de conexión, como se muestra en a continuación el ejemplo:

  jdbc:poalardb://1.2.XX.XX:5432,2.3.XX.XX:5432/postgres

  Nota

  Si configura varias direcciones IP, el controlador intenta conectarse a ellas de forma secuencial. Si no logra establecer conexión con ninguna de las direcciones IP, el intento falla. El tiempo de espera de conexión predeterminado para cada intento es de 10 segundos (connectTimeout). Para cambiar el periodo de tiempo de espera, agregue el parámetro connectTimeout a la cadena de conexión.

• P: ¿Cómo selecciono el tipo de cursor?

  R: Para versiones de JDK anteriores a Java 1.8, use Types.REF. Para Java 1.8 o versiones posteriores, use Types.REF_CURSOR.

• P: ¿Los nombres de columna se pueden devolver en mayúsculas de forma predeterminada?

  R: Sí. Agregue el parámetro oracleCase=true a la cadena de conexión JDBC para convertir a mayúsculas todos los nombres de columna devueltos. A continuación se muestra un ejemplo:

  jdbc:poalardb://1.2.XX.XX:5432,2.3.XX.XX:5432/postgres?oracleCase=true