Orígenes de datos JDBC - ApsaraDB for SelectDB - Centro de documentación de Alibaba Cloud

Un catálogo JDBC conecta SelectDB con bases de datos externas mediante el protocolo estándar JDBC. Una vez establecida la conexión, SelectDB sincroniza automáticamente los metadatos del origen de datos externo. Esto le permite ejecutar consultas federadas en MySQL, PostgreSQL, Oracle, SQLServer, ClickHouse, Doris, SAP HANA, Trino/Presto y OceanBase sin necesidad de mover los datos.

Requisitos previos

Antes de empezar, asegúrese de que:

Todos los nodos del clúster de origen de datos y su instancia de SelectDB se comuniquen a través de la red. Deben estar en la misma Virtual Private Cloud (VPC). Si no lo están, resuelva primero el problema de conectividad. Para obtener más información, consulte How do I resolve network connectivity issues between a SelectDB instance and a data source?
Las direcciones IP de todos los nodos del clúster de origen de datos estén agregadas a la lista de permitidos de la instancia de SelectDB. Para obtener más información, consulte Configure a whitelist.
Si el clúster de origen tiene su propia lista de permitidos, agregue el bloque CIDR de la instancia de SelectDB a dicha lista.
- Para obtener la dirección IP de VPC de la instancia de SelectDB, consulte ¿Cómo consulto las direcciones IP de la VPC a la que pertenece mi instancia de ApsaraDB SelectDB?
- Para obtener la dirección IP pública, ejecute el comando ping contra el endpoint público de la instancia de SelectDB.
Tenga conocimientos básicos sobre catálogos. Para obtener más información, consulte Data lakehouse.

Creación de un catálogo JDBC

Sintaxis

CREATE CATALOG <catalog_name>
PROPERTIES ("key"="value", ...)

Parámetros

Parámetro	Obligatorio	Predeterminado	Descripción
`user`	Sí	—	Nombre de usuario de la cuenta de la base de datos.
`password`	Sí	—	Contraseña de la cuenta de la base de datos.
`jdbc_url`	Sí	—	Cadena de conexión JDBC. El formato varía según la base de datos: MySQL — `jdbc:mysql://host:port/db`; PostgreSQL — `jdbc:postgresql://host:port/db`; Oracle — `jdbc:oracle:thin:@host:port:sid`; SQLServer — `jdbc:sqlserver://host:port;DataBaseName=db`. Consulte los ejemplos por base de datos que aparecen a continuación para ver la lista completa.
`driver_url`	Sí	—	Ruta al archivo JAR del controlador JDBC. Especifique un nombre de archivo (por ejemplo, `mysql-connector-java-8.0.25.jar`) para cargarlo desde el directorio local `jdbc_drivers/`, o bien una URL HTTP para descargar el archivo.
`driver_class`	Sí	—	Nombre de clase del controlador JDBC. Valores comunes: MySQL — `com.mysql.cj.jdbc.Driver`; PostgreSQL — `org.postgresql.Driver`; Oracle — `oracle.jdbc.driver.OracleDriver`; SQLServer — `com.microsoft.sqlserver.jdbc.SQLServerDriver`. Consulte los ejemplos por base de datos para otras bases de datos.
`lower_case_table_names`	No	`"false"`	Cuando es `true`, sincroniza los nombres de bases de datos y tablas en minúsculas. Consulte Sincronización de nombres en minúsculas.
`only_specified_database`	No	`"false"`	Cuando es `true`, sincroniza únicamente las bases de datos especificadas en `include_database_list`.
`include_database_list`	No	`""`	Solo surte efecto cuando `only_specified_database=true`. Lista de bases de datos que se van a sincronizar, separadas por comas. Distingue entre mayúsculas y minúsculas.
`exclude_database_list`	No	`""`	Solo surte efecto cuando `only_specified_database=true`. Lista de bases de datos que se van a excluir, separadas por comas. Distingue entre mayúsculas y minúsculas. Si una base de datos aparece en ambas listas, `exclude_database_list` tiene prioridad.

Ruta del paquete del controlador

El parámetro driver_url acepta dos formatos:

Nombre de archivo: por ejemplo, mysql-connector-java-8.0.25.jar. SelectDB busca en el directorio local jdbc_drivers/. Los siguientes cuatro paquetes de controladores vienen preinstalados:
- mysql-connector-java-8.0.25.jar
- postgresql-42.5.1.jar
- mssql-jdbc-11.2.3.jre8.jar
- ojdbc8.jar
URL HTTP: por ejemplo, https://doris-community-test-1308700295.cos.ap-hongkong.myqcloud.com/jdbc_driver/mysql-connector-java-8.0.25.jar. SelectDB descarga el archivo desde esta URL. Solo se admiten servicios HTTP sin autenticación.

Sincronización de nombres en minúsculas

Cuando lower_case_table_names=true, SelectDB mantiene un mapeo entre los nombres en minúsculas y los nombres reales. Así podrá consultar bases de datos y tablas con nombres en minúsculas, sin importar cómo estaban escritos originalmente.

Comportamiento por versión:

SelectDB 2.X: solo aplica para Oracle. Todos los nombres de bases de datos y tablas se convierten a mayúsculas antes de enviar la consulta a Oracle. Por ejemplo, si establece lower_case_table_names=true y Oracle tiene una tabla llamada TEST en el esquema TEST, puede consultarla con SELECT * FROM oracle_catalog.test.test. SelectDB convierte automáticamente test.test a TEST.TEST.
SelectDB 3.X y versiones posteriores: aplica para todas las bases de datos. Los nombres se convierten a su formato real antes de ejecutar la consulta. Si actualizó desde una versión anterior, ejecute REFRESH <catalog_name> para que este cambio surta efecto.

Restricciones:

Si dos nombres de bases de datos o tablas difieren únicamente en el uso de mayúsculas y minúsculas (por ejemplo, SelectDB y selectdb), SelectDB no podrá consultarlos debido a la ambigüedad.
Si el parámetro lower_case_table_names del frontend (FE) está configurado como 1 o 2, configure el parámetro lower_case_table_names del catálogo JDBC como true. Si el parámetro del FE es 0, puede configurarlo como true o false (valor predeterminado: false).

Sincronización de bases de datos específicas

Utilice only_specified_database, include_database_list y exclude_database_list en conjunto para limitar qué bases de datos sincroniza SelectDB.

Al conectarse mediante JDBC, también puede preseleccionar una base de datos directamente en jdbc_url. Por ejemplo, especifique el nombre de la base de datos en la URL de MySQL o use currentSchema en la URL de PostgreSQL.

Al usar include_database_list o exclude_database_list con Oracle, utilice ojdbc8.jar o una versión posterior.

Ejemplos por base de datos

MySQL

CREATE CATALOG jdbc_mysql PROPERTIES (
    "type"="jdbc",
    "user"="root",
    "password"="123456",
    "jdbc_url" = "jdbc:mysql://127.0.0.1:3306/demo",
    "driver_url" = "mysql-connector-java-8.0.25.jar",
    "driver_class" = "com.mysql.cj.jdbc.Driver"
)

Mapeo de niveles

SelectDB	MySQL
Catálogo	Servidor MySQL
Base de datos	Base de datos
Tabla	Tabla

Mapeo de tipos

Tipo de MySQL	Tipo de SelectDB	Notas
BOOLEAN	TINYINT
TINYINT	TINYINT
SMALLINT	SMALLINT
MEDIUMINT	INT
INT	INT
BIGINT	BIGINT
UNSIGNED TINYINT	SMALLINT	SelectDB no tiene tipo UNSIGNED; el rango se amplía al siguiente nivel.
UNSIGNED MEDIUMINT	INT	SelectDB no tiene tipo UNSIGNED; el rango se amplía al siguiente nivel.
UNSIGNED INT	BIGINT	SelectDB no tiene tipo UNSIGNED; el rango se amplía al siguiente nivel.
UNSIGNED BIGINT	LARGEINT
FLOAT	FLOAT
DOUBLE	DOUBLE
DECIMAL	DECIMAL
UNSIGNED DECIMAL(p,s)	DECIMAL(p+1,s) / STRING	Si `p+1 > 38`, se usa STRING.
DATE	DATE
TIMESTAMP	DATETIME
DATETIME	DATETIME
YEAR	SMALLINT
TIME	STRING
CHAR	CHAR
VARCHAR	VARCHAR
JSON	JSON
SET	STRING
BIT	BOOLEAN / STRING	BIT(1) se asigna a BOOLEAN; todos los demás tipos BIT se asignan a STRING.
TINYTEXT, TEXT, MEDIUMTEXT, LONGTEXT	STRING
BLOB, MEDIUMBLOB, LONGBLOB, TINYBLOB	STRING
TINYSTRING, STRING, MEDIUMSTRING, LONGSTRING	STRING
BINARY, VARBINARY	STRING
Otros	UNSUPPORTED

PostgreSQL

CREATE CATALOG jdbc_postgresql PROPERTIES (
    "type"="jdbc",
    "user"="root",
    "password"="123456",
    "jdbc_url" = "jdbc:postgresql://127.0.0.1:5432/demo",
    "driver_url" = "postgresql-42.5.1.jar",
    "driver_class" = "org.postgresql.Driver"
);

Mapeo de niveles

Una base de datos de SelectDB se asigna a un esquema de la base de datos PostgreSQL especificada en jdbc_url (por ejemplo, los esquemas en demo).

SelectDB	PostgreSQL
Catálogo	Base de datos
Base de datos	Esquema
Tabla	Tabla

SelectDB recupera los esquemas accesibles al ejecutar: SELECT nspname FROM pg_namespace WHERE has_schema_privilege('<UserName>', nspname, 'USAGE');

Mapeo de tipos

Tipo de PostgreSQL	Tipo de SelectDB	Notas
boolean	BOOLEAN
smallint / int2	SMALLINT
integer / int4	INT
bigint / int8	BIGINT
decimal / numeric	DECIMAL
real / float4	FLOAT
double precision	DOUBLE
smallserial	SMALLINT
serial	INT
bigserial	BIGINT
char	CHAR
varchar / text	STRING
timestamp	DATETIME
date	DATE
json / jsonb	JSON
time	STRING
interval	STRING
point / line / lseg / box / path / polygon / circle	STRING
cidr / inet / macaddr	STRING
bit	BOOLEAN / STRING	bit(1) se asigna a BOOLEAN; todos los demás tipos bit se asignan a STRING.
uuid	STRING
Otros	UNSUPPORTED

Oracle

CREATE CATALOG jdbc_oracle PROPERTIES (
    "type"="jdbc",
    "user"="root",
    "password"="123456",
    "jdbc_url" = "jdbc:oracle:thin:@127.0.0.1:1521:helowin",
    "driver_url" = "ojdbc8.jar",
    "driver_class" = "oracle.jdbc.driver.OracleDriver"
);

Mapeo de niveles

Una base de datos de SelectDB se asigna a un usuario en Oracle. Una tabla se asigna a una tabla a la que dicho usuario tiene permisos de acceso.

SelectDB	Oracle
Catálogo	Base de datos
Base de datos	Usuario
Tabla	Tabla

No se admite la sincronización de tablas SYNONYM de Oracle.

Mapeo de tipos

Tipo de Oracle	Tipo de SelectDB	Notas
number(p) / number(p,0)	TINYINT / SMALLINT / INT / BIGINT / LARGEINT	Se asigna según p: p < 3 → TINYINT; p < 5 → SMALLINT; p < 10 → INT; p < 19 → BIGINT; p > 19 → LARGEINT
number(p,s) [si s > 0 y p > s]	DECIMAL(p,s)
number(p,s) [si s > 0 y p < s]	DECIMAL(s,s)
number(p,s) [si s < 0]	TINYINT / SMALLINT / INT / BIGINT / LARGEINT	SelectDB establece p como `p+	s	`y aplica el mismo mapeo que` number(p)/number(p,0)`.
number (sin p ni s especificados)	No compatible	Actualmente, SelectDB no admite `NUMBER` de Oracle sin precisión ni escala explícitas.
decimal	DECIMAL
float / real	DOUBLE
DATE	DATETIME
TIMESTAMP	DATETIME
CHAR / NCHAR	STRING
VARCHAR2 / NVARCHAR2	STRING
LONG / RAW / LONG RAW / INTERVAL	STRING
Otros	UNSUPPORTED

SQLServer

Importante

En SelectDB 3.0.8 y versiones posteriores, incluya encrypt=false en jdbc_url.

CREATE CATALOG jdbc_sqlserver PROPERTIES (
    "type"="jdbc",
    "user"="SA",
    "password"="SelectDB123456",
    "jdbc_url" = "jdbc:sqlserver://localhost:1433;DataBaseName=SelectDB_test;encrypt=false",
    "driver_url" = "mssql-jdbc-11.2.3.jre8.jar",
    "driver_class" = "com.microsoft.sqlserver.jdbc.SQLServerDriver"
);

Mapeo de niveles

Una base de datos de SelectDB se asigna a un esquema de la base de datos SQLServer especificada en jdbc_url (por ejemplo, los esquemas en SelectDB_test).

SelectDB	SQLServer
Catálogo	Base de datos
Base de datos	Esquema
Tabla	Tabla

Mapeo de tipos

Tipo de SQLServer	Tipo de SelectDB
bit	BOOLEAN
tinyint	SMALLINT
smallint	SMALLINT
int	INT
bigint	BIGINT
real	FLOAT
float	DOUBLE
money	DECIMAL(19.4)
smallmoney	DECIMAL(10.4)
decimal / numeric	DECIMAL
date	DATE
datetime / datetime2 / smalldatetime	DATETIMEV2
char / varchar / text / nchar / nvarchar / ntext	STRING
binary / varbinary	STRING
time / datetimeoffset	STRING
Otros	UNSUPPORTED

Doris

SelectDB se conecta a Doris mediante el controlador JDBC de MySQL.

CREATE CATALOG jdbc_doris PROPERTIES (
    "type"="jdbc",
    "user"="root",
    "password"="123456",
    "jdbc_url" = "jdbc:mysql://127.0.0.1:9030?useSSL=false",
    "driver_url" = "mysql-connector-java-8.0.25.jar",
    "driver_class" = "com.mysql.cj.jdbc.Driver"
)

Mapeo de tipos

Tipo de Doris	Tipo de SelectDB	Notas
BOOLEAN	BOOLEAN
TINYINT	TINYINT
SMALLINT	SMALLINT
INT	INT
BIGINT	BIGINT
LARGEINT	LARGEINT
FLOAT	FLOAT
DOUBLE	DOUBLE
DECIMALV3	DECIMALV3 / STRING	Se selecciona según la precisión y la escala del campo DECIMAL.
DATE	DATE
DATETIME	DATETIME
CHAR	CHAR
VARCHAR	VARCHAR
STRING	STRING
TEXT	STRING
HLL	HLL	Establezca `return_object_data_as_binary=true` para consultar columnas HLL.
Array	Array	El mapeo interno de tipos sigue las reglas anteriores. No se admiten tipos complejos anidados.
BITMAP	BITMAP	Establezca `return_object_data_as_binary=true` para consultar columnas BITMAP.
Otros	UNSUPPORTED

ClickHouse

CREATE CATALOG jdbc_clickhouse PROPERTIES (
    "type"="jdbc",
    "user"="root",
    "password"="123456",
    "jdbc_url" = "jdbc:clickhouse://127.0.0.1:8123/demo",
    "driver_url" = "clickhouse-jdbc-0.4.2-all.jar",
    "driver_class" = "com.clickhouse.jdbc.ClickHouseDriver"
);

Mapeo de niveles

SelectDB	ClickHouse
Catálogo	Servidor ClickHouse
Base de datos	Base de datos
Tabla	Tabla

Mapeo de tipos

Tipo de ClickHouse	Tipo de SelectDB
Bool	BOOLEAN
String	STRING
Date / Date32	DATE
DateTime / DateTime64	DATETIME
Float32	FLOAT
Float64	DOUBLE
Int8	TINYINT
Int16 / UInt8	SMALLINT
Int32 / UInt16	INT
Int64 / UInt32	BIGINT
Int128 / UInt64	LARGEINT
Int256 / UInt128 / UInt256	STRING
DECIMAL	DECIMALV3 / STRING
Enum / IPv4 / IPv6 / UUID	STRING
Array	ARRAY
Otros	UNSUPPORTED

SAP HANA

CREATE CATALOG jdbc_hana PROPERTIES (
    "type"="jdbc",
    "user"="SYSTEM",
    "password"="SAPHANA",
    "jdbc_url" = "jdbc:sap://localhost:31515/TEST",
    "driver_url" = "ngdbc.jar",
    "driver_class" = "com.sap.db.jdbc.Driver"
)

Mapeo de niveles

SelectDB	SAP HANA
Catálogo	Base de datos
Base de datos	Esquema
Tabla	Tabla

Mapeo de tipos

Tipo de SAP HANA	Tipo de SelectDB
BOOLEAN	BOOLEAN
TINYINT	TINYINT
SMALLINT	SMALLINT
INTEGER	INT
BIGINT	BIGINT
SMALLDECIMAL	DECIMALV3
DECIMAL	DECIMALV3 / STRING
REAL	FLOAT
DOUBLE	DOUBLE
DATE	DATE
TIME	STRING
TIMESTAMP	DATETIME
SECONDDATE	DATETIME
VARCHAR	STRING
NVARCHAR	STRING
ALPHANUM	STRING
SHORTTEXT	STRING
CHAR	CHAR
NCHAR	CHAR

OceanBase

CREATE CATALOG jdbc_oceanbase PROPERTIES (
    "type"="jdbc",
    "user"="root",
    "password"="123456",
    "jdbc_url" = "jdbc:oceanbase://127.0.0.1:2881/demo",
    "driver_url" = "oceanbase-client-2.4.2.jar",
    "driver_class" = "com.oceanbase.jdbc.Driver"
)

SelectDB detecta automáticamente si OceanBase se ejecuta en modo MySQL u Oracle. El mapeo de niveles y el mapeo de tipos siguen las reglas correspondientes de MySQL u Oracle. Consulte las secciones MySQL y Oracle.

Consulta de datos

Use el nombre de tres partes <catalog>.<database>.<table> para consultar datos en un catálogo JDBC:

SELECT * FROM mysql_catalog.mysql_database.mysql_table WHERE k1 > 1000 AND k3 = 'term';

Caracteres de escape: SelectDB escapa automáticamente los nombres de campos y tablas según los estándares de cada base de datos. Utiliza comillas invertidas para MySQL, comillas dobles para PostgreSQL y Oracle, y corchetes para SQLServer. Esto puede hacer que los nombres de los campos distingan entre mayúsculas y minúsculas. Ejecute EXPLAIN en una consulta para ver el SQL escapado que se envía a la base de datos remota.

Transferencia de predicados

SelectDB transfiere las condiciones de la cláusula WHERE al origen de datos externo para filtrar los datos en el origen. Esto reduce la transferencia innecesaria de datos y mejora el rendimiento de las consultas.

Cuando enable_func_pushdown=true (variable de sesión), SelectDB también transfiere las funciones de la cláusula WHERE al origen de datos externo. Esta función solo es compatible con MySQL. Las siguientes funciones quedan excluidas de la transferencia: DATE_TRUNC y MONEY_FORMAT. Para deshabilitar la transferencia de funciones, establezca enable_func_pushdown=false. Ejecute EXPLAIN para comprobar qué condiciones se transfieren.

Límite de filas

Si una consulta incluye la palabra clave LIMIT, SelectDB la traduce a la sintaxis adecuada para la base de datos de destino.

Escritura de datos

Después de crear un catálogo JDBC, escriba datos mediante INSERT INTO o INSERT INTO...SELECT:

-- Write a single row
INSERT INTO mysql_catalog.mysql_database.mysql_table VALUES(1, "doris");

-- Write query results
INSERT INTO mysql_catalog.mysql_database.mysql_table SELECT * FROM table;

Para grandes volúmenes de datos, utilice INSERT INTO...SELECT en lugar de INSERT INTO. La instrucción INSERT INTO resulta ineficiente para escrituras masivas.

Transacciones

Los datos de SelectDB se escriben en un catálogo JDBC por lotes. Si una importación se interrumpe, podría ser necesario revertir los datos ya escritos. Para gestionar esto, el catálogo JDBC admite transacciones en la escritura de datos. Para habilitar la compatibilidad con transacciones, configure la variable de sesión enable_odbc_transcation:

SET enable_odbc_transcation = TRUE;

Las transacciones garantizan la atomicidad de las escrituras en tablas externas JDBC, pero reducen el rendimiento de escritura. Habilítelas únicamente cuando la consistencia de los datos sea crítica.