AnalyticDB:Write data by using the Client SDK

Maven

Agregue la siguiente dependencia a su archivo pom.xml:

<dependency>
  <groupId>com.alibaba.cloud.analyticdb</groupId>
  <artifactId>adb4pgclient</artifactId>
  <version>1.0.16</version>
</dependency>

El SDK depende de los siguientes paquetes. Si se presentan conflictos de versiones, revise y resuelva estas dependencias:

• druid 1.1.17

• postgresql-jdbc 42.3.9

• commons-lang3 3.4

• slf4j-api 1.7.24

• slf4j-log4j12 1.7.24

JAR sin conexión

Descargue directamente los paquetes JAR sin conexión: adb4pgclient-1.0.16.jar y adb4pgclient-1.0.16-jar-with-dependencies.jar.

public class Adb4pgClientUsage {
    public void demo() {
        // 1. Configure the connection
        DatabaseConfig databaseConfig = new DatabaseConfig();
        databaseConfig.setHost("100.100.100.100");   // Connection address of the instance
        databaseConfig.setPort(8888);                // Default: 5432
        databaseConfig.setUser("your user name");
        databaseConfig.setPassword("your password");
        databaseConfig.setDatabase("your database name");

        // 2. Specify the target tables and columns
        // Call addTable separately for tables in different schemas.
        // Pass null for the schema to use the default schema 'public'.
        List<String> tables = new ArrayList<String>();
        tables.add("your table name 1");
        tables.add("your table name 2");
        databaseConfig.addTable(tables, "table schema name");

        // Specify columns per table. Use "*" to write to all columns.
        List<String> columns = new ArrayList<String>();
        columns.add("column1");
        columns.add("column2");
        databaseConfig.setColumns(columns, "your table name 1", "table schema name");
        databaseConfig.setColumns(Collections.singletonList("*"), "your table name 2", "table schema name");

        // 3. Set optional write behavior (all settings must be configured before creating the client)
        databaseConfig.setEmptyAsNull(false);      // Whether to treat empty strings as null. Default: false.
        databaseConfig.setInsertIgnore(true);      // Whether to ignore rows that cause primary key conflicts. Default: false (conflicts overwrite existing rows).
        databaseConfig.setRetryTimes(3);           // Retry count on commit exception. Default: 3.
        databaseConfig.setRetryIntervalTime(1000); // Retry interval in milliseconds. Default: 1000.

        // 4. Initialize the client. No DatabaseConfig changes take effect after this point.
        Adb4pgClient adbClient = new Adb4pgClient(databaseConfig);

        // 5. Add rows to the buffer using setColumn (creates a new Row per record)
        for (int i = 0; i < 10; i++) {
            Row row = new Row(columns.size());
            row.setColumn(0, i);                   // Column index must match the column order set above
            row.setColumn(1, "string value");
            // If the buffer exceeds commitSize, an autocommit triggers before the new row is added.
            // Handle AdbClientException with error code COMMIT_ERROR_DATA_LIST if autocommit fails.
            adbClient.addRow(row, "your table name 1", "table schema name");
        }

        // Use updateColumn when you want to reuse the same Row instance across records
        Row row = new Row();
        row.setColumn(0, 10);
        row.setColumn(1, "2018-01-01 08:00:00");
        adbClient.addRow(row, "your table name 1", "table schema name");
        row.updateColumn(0, 11);
        row.updateColumn(1, "2018-01-02 08:00:00");
        adbClient.addRow(row, "your table name 1", "table schema name");

        // Add rows in Map format (column name to value)
        Map<String, String> rowMap = new HashMap<String, String>();
        rowMap.put("t1", "12");
        rowMap.put("t2", "string value");
        adbClient.addMap(rowMap, "your table name 2", "table schema name");

        // 6. Commit the buffer. Data is written to AnalyticDB for PostgreSQL only after a successful commit.
        try {
            adbClient.commit();
        } catch (Exception e) {
            // Handle exception: inspect the error code and decide whether to retry or log and skip
        } finally {
            adbClient.stop(); // Releases thread pools. Throws an exception if uncommitted data remains.
        }
    }
}

Clase DatabaseConfig

DatabaseConfig almacena toda la configuración de conexión y del comportamiento de escritura. Configure todos los parámetros antes de pasar este objeto a Adb4pgClient. La configuración no se puede modificar después de inicializar el cliente.

Clase Row

Utilice Row para escribir datos registro por registro.

Clase Adb4pgClient

Adb4pgClient es la interfaz principal de escritura. Todas las operaciones de escritura almacenan los datos en un búfer hasta que se llama a commit().

Clase ColumnInfo

Códigos de error

Seguridad de hilos

El SDK no es seguro para hilos. En un entorno multiproceso, cada hilo debe mantener su propia instancia de Adb4pgClient. Compartir un solo cliente entre varios hilos genera contención en la escritura y convierte al cliente compartido en un cuello de botella de rendimiento.

Confirmación y durabilidad de los datos

Los datos se escriben en AnalyticDB for PostgreSQL únicamente después de que commit() se ejecuta correctamente. Cuando el cliente lanza una excepción, inspeccione el código de error para decidir si debe reintentar los registros fallidos o registrarlos y omitirlos.

Tamaño del lote

Evite realizar confirmaciones demasiado frecuentes con lotes pequeños, ya que las ventajas de eficiencia de la escritura por lotes se pierden cuando estos son reducidos. Procure agregar como mínimo 10,000 registros antes de llamar a commit(). Los lotes pequeños incrementan el número de viajes de ida y vuelta por la red y reducen el throughput.

Aumentar el número de hilos de escritura no siempre mejora el rendimiento. Dado que las aplicaciones suelen almacenar datos en memoria antes de confirmarlos, un número elevado de hilos puede aumentar la presión sobre la memoria y provocar una recolección de basura (GC) más frecuente. Supervise el estado de la GC de su aplicación al ajustar el recuento de hilos.

Bloqueo de la configuración

Finalice toda la configuración de DatabaseConfig antes de pasar el objeto de configuración a Adb4pgClient. Ningún cambio en la configuración surte efecto después de inicializar el cliente.

Operaciones SQL

El SDK está optimizado para escrituras masivas (INSERT). Para todas las demás operaciones SQL (consultas, DDL, actualizaciones y eliminaciones), utilice getConnection() para obtener una conexión JDBC y operar mediante las interfaces JDBC estándar.