Skip to main content

JDBC catalogs

Gravitino connects relational databases and warehouses through ten JDBC connectors: MySQL, PostgreSQL, Oracle, SQL Server, BigQuery, ClickHouse, Doris, StarRocks, OceanBase, and Hologres.

They share one property set for the connection, the connection pool, and create-time verification, and each catalog loads a JDBC driver class named by jdbc-driver. Each connector page covers only what it adds or constrains on top of the shared set.

Quick start​

The example connects a MySQL server as the catalog mysql_sales and lists its databases as schemas. The MySQL driver does not ship in the image, so supply it first, as described in JDBC driver.

  1. Start the catalog. Open Connect → Catalogs and click + Catalog. Enter mysql_sales as the Catalog name, keep Relational as the Catalog type, and choose MySQL under Databases and warehouses in Select provider.

  2. Enter the connection. Under Connection, enter jdbc:mysql://mysql.example.com:3306 as the URL, and the User and Password Gravitino connects as. Advanced holds Cloud / region and a Properties list for any other property in Shared properties. The UI fills in jdbc-driver from the provider.

  3. Test and create it. Click Test connection, then Create catalog. Gravitino tests the connection again before it saves the catalog.

  4. List the schemas. In Explore, open mysql_sales. The schemas listed are the MySQL databases, read from the server.

Shared properties​

PropertyRequiredDefaultNotes
jdbc-urlYesThe JDBC connection string
jdbc-driverYesThe driver class name. See JDBC driver for when it is filled in for you
jdbc-userYesThe user Gravitino connects as
jdbc-passwordYesHidden, not returned when the catalog is loaded
jdbc-databaseNoRequired by some connectors; see below
jdbc.pool.min-sizeNo2Minimum idle connections in the pool
jdbc.pool.max-sizeNo10Maximum connections in the pool
jdbc.pool.test-on-borrowNotrueHidden. Validates a connection before use
jdbc.pool.connect-timeout-msNo30000Connect timeout in milliseconds, from 1 to 2147483647
verify-on-createNotrueHidden. Probes the source at create and fails the create if it cannot be reached

jdbc-database is optional in the shared definition, but some connectors need a database. PostgreSQL and SQL Server take it from jdbc-database or from jdbc-url (the path for PostgreSQL, databaseName for SQL Server), and the create fails when neither names one or when the two differ. Hologres requires jdbc-database itself. Read the connector page rather than assuming.

Pool sizing is per catalog, not per server. Ten JDBC catalogs at the default maximum can open a hundred connections against their sources, so check the total against the connection limits those sources enforce.

jdbc.pool.connect-timeout-ms is translated into each driver's own timeout parameter so an unreachable source fails fast. Pooled connections get only the connect timeout, so long-running operations are not cut off. The create-time probe also gets a read timeout. A timeout already set in jdbc-url wins. The SQL Server connector does not translate it; set loginTimeout in jdbc-url instead.

Set verify-on-create to false to register a catalog whose source is temporarily unavailable.

A property with the gravitino.bypass. prefix is passed to the connection pool with the prefix removed, so gravitino.bypass.maxWaitMillis sets the pool's maxWaitMillis.

JDBC driver​

The UI fills in jdbc-driver from the provider when it is omitted, for both Test connection and Create catalog. The public REST create endpoint, POST /api/metalakes/{metalake}/catalogs, and the clients that call it do not, so REST and client requests must supply jdbc-driver. BigQuery is the exception: its connector defaults jdbc-driver itself. A driver you supply is always kept.

If the driver class is not on the server classpath, the create fails and names the missing class.

ConnectorProviderDriver classIn the imageChart setting
MySQLjdbc-mysqlcom.mysql.cj.jdbc.DriverNogravitino.jdbcDrivers.mysql
PostgreSQLjdbc-postgresqlorg.postgresql.DriverYes
Oraclejdbc-oracleoracle.jdbc.OracleDriverYes
SQL Serverjdbc-sqlservercom.microsoft.sqlserver.jdbc.SQLServerDriverYes
BigQueryjdbc-bigquerycom.simba.googlebigquery.jdbc42.DriverNogravitino.jdbcDrivers.bigquery
ClickHousejdbc-clickhousecom.clickhouse.jdbc.ClickHouseDriverYes
Dorisjdbc-doriscom.mysql.cj.jdbc.DriverNogravitino.jdbcDrivers.mysql
StarRocksjdbc-starrockscom.mysql.cj.jdbc.DriverNogravitino.jdbcDrivers.mysql
OceanBasejdbc-oceanbasecom.mysql.cj.jdbc.DriverNogravitino.jdbcDrivers.mysql
Hologresjdbc-hologresorg.postgresql.DriverYes

The driver class shown is the one the UI fills in. OceanBase connects through MySQL Connector/J with a jdbc:mysql:// URL; see OceanBase.

MySQL Connector/J is licensed under the GPL and the Simba BigQuery driver is not redistributed either, so neither ships in the image. The chart supplies them at start: it downloads each enabled driver from its default URL, verifies a pinned sha256, and links it onto the classpath. Doris, StarRocks, and OceanBase use the same MySQL Connector/J as the MySQL connector. Enable Connector/J only if you accept its license.

my-values.yaml
gravitino:
  jdbcDrivers:
    enabled: true
    mode: download
    mysql:
      enabled: true
    bigquery:
      enabled: true

Enable only the drivers your catalogs use. For an internal repository, an HTTP proxy, a driver image, or an existing volume, see "Supply JDBC drivers at runtime" in the chart's install guide.

Last updated on