PolarDB:JDBC

Prérequis

• Vous avez créé un compte de base de données dans le cluster PolarDB. Pour plus d'informations, consultez la rubrique Création d'un compte de base de données.

• Les adresses IP des hôtes devant accéder au cluster PolarDB figurent dans une liste d'autorisation. Pour plus d'informations, consultez la rubrique Configuration d'une liste d'autorisation de cluster.

Informations générales

Le pilote JDBC pour PolarDB for PostgreSQL (Compatible avec Oracle) repose sur le pilote JDBC PostgreSQL open source. Il utilise le protocole réseau natif de PostgreSQL, ce qui permet aux programmes Java de se connecter à la base de données avec du code Java standard, indépendant de la base de données.

Le pilote JDBC utilise le protocole PostgreSQL 3.0 et est compatible avec Java 6 (JDBC 4.0), Java 7 (JDBC 4.1) et Java 8 (JDBC 4.2).

Configuration du pilote JDBC

Pour utiliser le pilote JDBC dans une application Java, ajoutez le chemin d'accès à son fichier JAR à votre variable CLASSPATH. Par exemple, si le fichier JAR se trouve dans le répertoire /usr/local/polardb/share/java/, exécutez la commande suivante pour ajouter son chemin à la variable CLASSPATH :

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

Exemple :

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

Pour vérifier la version de votre pilote JDBC, exécutez la commande suivante :

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

Exemple :

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

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

• Chargement du pilote JDBC

  Exécutez la commande suivante dans votre application pour charger le pilote JDBC :

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

• Connexion à la base de données

  Dans JDBC, une URL de connexion représente la connexion à la base de données. Exemple :

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

  Paramètre	Exemple	Description
  Préfixe d'URL	jdbc:polardb://	Le préfixe d'URL pour la connexion à PolarDB est toujours jdbc:polardb://.
  Endpoint	pc-***.o.polardb.rds.aliyuncs.com	L'endpoint du cluster PolarDB. Pour plus d'informations, consultez la rubrique Affichage ou demande d'un endpoint.
  Port	1521	Le port du cluster PolarDB. La valeur par défaut est 1521.
  Base de données	polardb_test	Le nom de la base de données à laquelle se connecter.
  Nom d'utilisateur	test	Le nom d'utilisateur du cluster PolarDB.
  Mot de passe	Pw123456	Le mot de passe associé au nom d'utilisateur du cluster PolarDB.

• Interrogation des données et traitement des résultats

  Pour exécuter une requête, créez un objet Statement, PreparedStatement ou CallableStatement.

  L'exemple précédent utilise un objet Statement. L'exemple suivant montre comment utiliser un objet 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 objet CallableStatement sert à appeler une procédure stockée. Voici un exemple :

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

  La procédure stockée getName utilisée dans le code précédent est définie comme suit :

  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;

  Remarque

  Pour les procédures stockées qui renvoient un curseur, le type de curseur dépend de la version de Java :

  • Pour Java 8 ou versions ultérieures, utilisez Types.REF_CURSOR.

  • Pour les versions antérieures à Java 8, utilisez Types.REF.

• Définition de la taille de récupération (fetch size)

  Par défaut, le pilote récupère tous les résultats de la requête depuis la base de données en une seule fois. Pour les grands ensembles de résultats, cela peut consommer une quantité importante de mémoire client et provoquer une erreur d'épuisement de la mémoire (OOM). Pour éviter ce problème, JDBC propose un ResultSet basé sur un curseur afin de récupérer les données par lots. Pour utiliser cette fonctionnalité, vous devez :

  • Définir la propriété FetchSize. La valeur par défaut de FetchSize est 0, ce qui signifie que toutes les données sont récupérées en une seule fois.

  • Définir la propriété autoCommit de la connexion sur 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();

Intégration avec Maven

Si votre projet Java est construit avec Maven, exécutez la commande suivante pour installer le package du pilote JDBC PolarDB dans votre référentiel 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>

Exemple :

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

Ajoutez la dépendance suivante au fichier pom.xml de votre projet Maven.

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

Exemple :

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

Intégration avec Hibernate

Si votre projet utilise Hibernate, configurez la classe de pilote et le dialecte pour PolarDB dans votre fichier 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>

Intégration avec Druid

• Par défaut, les versions de Druid 1.1.24 et ultérieures prennent en charge le pilote PolarDB. Vous n'avez pas besoin de définir les paramètres driverClassName et dbtype.

• Pour les versions antérieures à Druid 1.1.24, vous devez explicitement définir les paramètres driverClassName et dbtype :

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

  Remarque

  Les versions de Druid antérieures à 1.1.24 ne prennent pas en charge nativement PolarDB. Par conséquent, vous devez définir le paramètre dbtype sur postgresql.

Si vous devez chiffrer le mot de passe de la base de données dans le pool de connexions Druid, consultez la documentation relative au chiffrement du mot de passe de la base de données.

Intégration avec Activiti

Si votre application utilise le framework Activiti pour la gestion des processus métier, l'erreur suivante peut survenir lors de l'initialisation d'une source de données PolarDB.

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

Cette erreur se produit car le mappage intégré des noms de produits de base de données vers les types de base de données dans Activiti ne contient pas d'entrée pour PolarDB. Pour résoudre ce problème, créez une sous-classe de SpringProcessEngineConfiguration et remplacez la méthode buildProcessEngine afin de spécifier explicitement le type de base de données. Le code suivant illustre cette approche.

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

Placez la sous-classe SpringProcessEngineConfiguration dans votre projet. Ensuite, dans le fichier de configuration, définissez le moteur pour qu'il charge la configuration à partir de cette classe lors de l'initialisation. L'exemple de code ci-dessous montre comment procéder.

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

Intégration avec Quartz

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

Intégration avec WebSphere

Intégration avec MyBatis

Lorsque vous utilisez MyBatis, vous devrez peut-être configurer un fournisseur d'ID de base de données databaseIdProvider. Le code suivant présente la configuration par défaut :

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

Un élément databaseIdProvider établit un mappage entre un nom de produit de base de données et un alias spécifique, qui correspond à l'élément databaseId. Cela garantit qu'un nom de produit de base de données est toujours mappé au même alias, même si le nom du produit change selon les différentes versions de la base de données.

Dans un fichier de mappage XML MyBatis, vous pouvez ajouter l'attribut databaseId à une instruction SQL. Cela garantit que l'instruction s'exécute uniquement sur la base de données correspondant à cet ID de base de données. Lorsque MyBatis charge le fichier de mappage, il charge uniquement les instructions dont l'ID de base de données correspond, ainsi que toutes les instructions qui ne possèdent pas d'attribut databaseId.

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

FAQ

• Q : Comment choisir un pilote JDBC ? Puis-je utiliser un pilote communautaire open source ?

  R : PolarDB for PostgreSQL (Compatible avec Oracle) est basé sur PostgreSQL open source, mais certaines de ses fonctionnalités nécessitent une prise en charge au niveau du pilote. Par conséquent, nous recommandons d'utiliser le pilote JDBC officiel PolarDB, que vous pouvez télécharger depuis la page officielle de téléchargement des pilotes.

• Q : Le pilote JDBC PolarDB est-il disponible dans les dépôts Maven publics ?

  R : Non. Le pilote n'est pas disponible dans les dépôts Maven publics. Vous devez télécharger le fichier JAR depuis le site web officiel et, pour les projets Maven, l'installer manuellement dans votre référentiel local.

• Q : Comment vérifier le numéro de version du pilote ?

  R : Exécutez la commande java -jar <driver-name> pour afficher le numéro de version.

• Q : L'URL de connexion prend-elle en charge plusieurs adresses IP et ports ?

  R : Oui, le pilote JDBC PolarDB for PostgreSQL (Compatible avec Oracle) vous permet de spécifier plusieurs paires hôte-port dans l'URL de connexion, comme illustré dans l'exemple suivant :

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

  Remarque

  Si vous configurez plusieurs adresses IP, le pilote tente de s'y connecter séquentiellement. Si une connexion ne peut être établie avec aucune des adresses IP, la tentative de connexion échoue. Le délai d'attente de connexion par défaut pour chaque tentative est de 10 secondes (connectTimeout). Pour modifier ce délai, vous pouvez ajouter le paramètre connectTimeout à la chaîne de connexion.

• Q : Comment choisir le type de curseur ?

  R : Pour les versions du JDK antérieures à Java 1.8, utilisez Types.REF. Pour Java 1.8 ou les versions ultérieures, vous pouvez utiliser Types.REF_CURSOR.

• Q : Les noms de colonnes peuvent-ils être renvoyés en majuscules par défaut ?

  R : Oui. Ajoutez le paramètre oracleCase=true à la chaîne de connexion JDBC pour convertir tous les noms de colonnes renvoyés en majuscules. Voici un exemple :

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