AnalyticDB:Write data by using the Client SDK

Maven

Adicione a seguinte dependência ao seu arquivo pom.xml:

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

O SDK depende dos seguintes pacotes. Caso ocorram conflitos de versão, verifique e resolva estas versões:

• druid 1.1.17

• postgresql-jdbc 42.3.9

• commons-lang3 3.4

• slf4j-api 1.7.24

• slf4j-log4j12 1.7.24

JAR offline

Baixe diretamente os pacotes JAR offline: adb4pgclient-1.0.16.jar e 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.
        }
    }
}

Classe DatabaseConfig

A classe DatabaseConfig armazena todas as configurações de conexão e comportamento de gravação. Configure todos os parâmetros antes de passá-la para o Adb4pgClient. Não é possível alterar as configurações após a inicialização do cliente.

Classe Row

Utilize a classe Row para gravar dados registro por registro.

Classe Adb4pgClient

A classe Adb4pgClient é a interface principal de gravação. Todas as operações de gravação armazenam dados em buffer até que commit() seja chamado.

Classe ColumnInfo

Códigos de erro

Segurança de threads

O SDK não é seguro para threads. Em um ambiente multithread, cada thread deve manter sua própria instância de Adb4pgClient. Compartilhar um único cliente entre threads cria contenção de gravação e transforma o cliente compartilhado em um gargalo de desempenho.

Commit e durabilidade dos dados

Os dados são gravados no AnalyticDB for PostgreSQL somente após o sucesso de commit(). Quando o cliente lançar uma exceção, inspecione o código de erro para decidir se deve tentar novamente os registros com falha ou registrá-los em log e ignorá-los.

Tamanho do lote

Evite confirmar transações com muita frequência usando lotes pequenos — os ganhos de eficiência da gravação em lote se perdem quando os lotes são reduzidos demais. Procure adicionar pelo menos 10.000 registros antes de chamar commit(). Lotes pequenos aumentam o número de idas e vindas na rede e reduzem o throughput.

Aumentar o número de threads de gravação nem sempre melhora o desempenho. Como os aplicativos geralmente armazenam dados em buffer na memória antes de confirmar, uma quantidade elevada de threads pode aumentar a pressão sobre a memória e acionar coletas de lixo (GC) mais frequentes. Monitore o status de GC do seu aplicativo ao ajustar a contagem de threads.

Bloqueio de configuração

Finalize todas as configurações de DatabaseConfig antes de passar o objeto de configuração para o Adb4pgClient. Nenhuma alteração de configuração surte efeito após a inicialização do cliente.

Operações SQL

O SDK é otimizado para gravações em massa (INSERT). Para todas as outras operações SQL — consultas, DDL, atualizações e exclusões — use getConnection() para obter uma conexão JDBC e opere por meio das interfaces JDBC padrão.