PolarDB:JDBC

Pré-requisitos

• Crie uma conta de banco de dados no cluster PolarDB. Para mais informações, consulte Create a database account.

• Adicione os endereços IP dos hosts que precisam acessar o cluster PolarDB a uma lista de permissões. Para mais informações, consulte Set a cluster whitelist.

Informações básicas

O driver JDBC para PolarDB for PostgreSQL (Compatible with Oracle) baseia-se no driver JDBC open-source do PostgreSQL. Ele utiliza o protocolo de rede nativo do PostgreSQL e permite que programas Java se conectem ao banco de dados com código Java padrão, independente de banco de dados.

O driver JDBC usa o protocolo PostgreSQL 3.0 e é compatível com Java 6 (JDBC 4.0), Java 7 (JDBC 4.1) e Java 8 (JDBC 4.2).

Configure o driver JDBC

Para usar o driver JDBC em uma aplicação Java, adicione o caminho do arquivo JAR ao CLASSPATH. Por exemplo, se o arquivo JAR estiver no diretório /usr/local/polardb/share/java/, execute o comando abaixo para adicionar o caminho ao CLASSPATH:

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

Exemplo:

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

Para verificar a versão do driver JDBC, execute este comando:

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

Exemplo:

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

Conecte-se ao 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();
    }
  }

• Carregue o driver JDBC

  Execute o seguinte comando na aplicação para carregar o driver JDBC:

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

• Conecte-se ao banco de dados

  No JDBC, uma URL de conexão representa a conexão com o banco de dados. Exemplo:

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

  Parâmetro	Exemplo	Descrição
  Prefixo da URL	jdbc:polardb://	O prefixo da URL para conexão com o PolarDB é sempre jdbc:polardb://.
  Endpoint	pc-***.o.polardb.rds.aliyuncs.com	O endpoint do cluster PolarDB. Para mais informações, consulte View or apply for an endpoint.
  Porta	1521	A porta do cluster PolarDB. O valor padrão é 1521.
  Banco de dados	polardb_test	Nome do banco de dados de destino.
  Nome de usuário	test	Nome de usuário do cluster PolarDB.
  Senha	Pw123456	Senha do usuário do cluster PolarDB.

• Consulte dados e processe resultados

  Para executar uma consulta, crie um objeto Statement, PreparedStatement ou CallableStatement.

  O exemplo anterior usa um objeto Statement. O exemplo a seguir demonstra o uso de um 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));
  }

  Use um CallableStatement para chamar stored procedures. Exemplo:

  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);

  A definição da stored procedure getName usada no código anterior é:

  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

  Em stored procedures que retornam cursor, o tipo depende da versão do Java:

  • Java 8 ou posterior: use Types.REF_CURSOR.

  • Anteriores ao Java 8: use Types.REF.

• Defina o tamanho de busca (fetch size)

  Por padrão, o driver busca todos os resultados da consulta de uma só vez. Em grandes conjuntos de resultados, isso pode consumir muita memória do cliente e causar erro de Out of Memory (OOM). Para evitar esse problema, o JDBC oferece um ResultSet baseado em cursor para buscar dados em lotes. Para usar esse recurso:

  • Defina o FetchSize. O valor padrão é 0, indicando que todos os dados são buscados simultaneamente.

  • Defina a propriedade autoCommit da conexão como 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();

Integração com Maven

Se o projeto Java utilizar Maven, execute o comando abaixo para instalar o pacote do driver JDBC do PolarDB no repositório 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>

Exemplo:

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

Adicione a dependência abaixo ao arquivo pom.xml do projeto Maven.

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

Exemplo:

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

Integração com Hibernate

Se o projeto usar Hibernate, configure a classe do driver e o dialeto do PolarDB no arquivo 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>

Integração com Druid

• O Druid 1.1.24 e versões posteriores oferecem suporte nativo ao driver do PolarDB. Não é necessário definir os parâmetros driverClassName e dbtype.

• Nas versões anteriores ao Druid 1.1.24, defina explicitamente os parâmetros driverClassName e dbtype:

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

  Nota

  Versões do Druid anteriores à 1.1.24 não têm suporte nativo ao PolarDB. Portanto, defina o parâmetro dbtype como postgresql.

Para criptografar a senha do banco de dados no pool de conexões do Druid, consulte Criptografia de senha de banco de dados.

Integração com Activiti

Se a aplicação usar o framework Activiti para gerenciamento de processos de negócios, o erro abaixo poderá ocorrer durante a inicialização de uma fonte de dados do PolarDB.

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

Esse erro ocorre porque o mapeamento interno do Activiti entre nomes de produtos e tipos de banco de dados não inclui o PolarDB. Para resolver, crie uma subclasse de SpringProcessEngineConfiguration e sobrescreva o método buildProcessEngine para especificar explicitamente o tipo de banco de dados. Exemplo:

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();
    }
}

Insira a subclasse SpringProcessEngineConfiguration no projeto. Depois, configure o mecanismo no arquivo de configuração para carregar essa classe durante a inicialização. Exemplo:

<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>

Integração com Quartz

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

Integração com WebSphere

Integração com MyBatis

Ao usar o MyBatis, talvez seja necessário configurar um databaseIdProvider. A configuração padrão é:

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

Um databaseIdProvider mapeia o nome do product de banco de dados para um alias específico, denominado databaseId. Isso garante que o nome do product corresponda sempre ao mesmo alias, mesmo que o nome mude entre versões diferentes.

Em arquivos de mapeamento XML do MyBatis, adicione o atributo databaseId a uma instrução SQL para executá-la apenas no banco de dados correspondente. Ao carregar o arquivo de mapeamento, o MyBatis importa somente as instruções com databaseId correspondente e aquelas sem esse atributo.

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

Perguntas frequentes

• P: Como selecionar um driver JDBC? Posso usar um driver da comunidade open-source?

  R: O PolarDB for PostgreSQL (Compatible with Oracle) baseia-se no PostgreSQL open-source, mas alguns recursos exigem suporte no nível do driver. Recomendamos o uso do driver JDBC oficial do PolarDB, disponível na página oficial de downloads.

• P: O driver JDBC do PolarDB está disponível em repositórios públicos do Maven?

  R: Não. O driver não está disponível em repositórios públicos do Maven. Baixe o arquivo JAR no site oficial e instale-o manualmente no repositório local para projetos Maven.

• P: Como verifico a versão do driver?

  R: Execute o comando java -jar <driver-name> para visualizar a versão.

• P: A URL de conexão suporta múltiplos endereços IP e portas?

  R: Sim. O driver JDBC do PolarDB for PostgreSQL (Compatible with Oracle) permite especificar vários pares de host e porta na URL de conexão. Exemplo:

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

  Nota

  Ao configurar múltiplos endereços IP, o driver tenta conectar-se a eles sequencialmente. Se nenhuma conexão for estabelecida, a tentativa falhará. O tempo limite padrão por tentativa é de 10 segundos (connectTimeout). Para alterar esse período, adicione o parâmetro connectTimeout à string de conexão.

• P: Como seleciono o tipo de cursor?

  R: Para versões do JDK anteriores ao Java 1.8, use Types.REF. Para Java 1.8 ou posterior, utilize Types.REF_CURSOR.

• P: Os nomes das colunas podem ser retornados em maiúsculas por padrão?

  R: Sim. Adicione o parâmetro oracleCase=true à string de conexão JDBC para converter todos os nomes de colunas retornados para maiúsculas. Exemplo:

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