Documentation / Connectors

Generic JDBC Connector

Connect any JDBC-speaking database to Nexus by supplying a driver class, a connection URL, and the driver JAR — the same substrate that powers NetSuite SuiteAnalytics Connect.

The generic JDBC connector points Nexus at any database that ships a JDBC driver. You supply three things — the driver class name, a connection URL, and the driver JAR — and the database becomes a queryable Nexus bridge with read, write, discovery, and SQL pushdown, exactly like the native PostgreSQL or SQL Server connectors. This is the "any SQL database" answer that complements the generic HTTP/REST connector's "any REST API." This page is for engineers connecting Oracle, Db2, Snowflake, Databricks, MariaDB, or any other JDBC source that has no dedicated Nexus adapter.

When to use this connector

Use the generic JDBC connector when your source is a SQL database that speaks JDBC but isn't one of the natively-adapted engines. Common targets:

Oracle Database (and, via the same driver family, NetSuite SuiteAnalytics Connect — see below)
IBM Db2
Snowflake
Databricks / Spark SQL
MariaDB, Amazon Redshift, Google BigQuery (via its JDBC driver), and other JDBC-exposed warehouses

If a native connector exists for your database — PostgreSQL, MySQL, SQL Server — prefer it: the native adapters ship their driver, tune dialect specifics (paging, merge syntax, identifier quoting), and require no JAR upload. Reach for generic JDBC when there is no native option.

Configuration

A generic JDBC bridge is defined by three required pieces plus credentials:

Field	Description
`driver_class`	The fully-qualified JDBC driver class, e.g. `oracle.jdbc.OracleDriver`, `com.snowflake.client.jdbc.SnowflakeDriver`, `com.ibm.db2.jcc.DB2Driver`
`connection_url`	The JDBC URL, e.g. `jdbc:oracle:thin:@//host:1521/service`, `jdbc:snowflake://acct.snowflakecomputing.com/?db=SALES`
Driver JAR	The vendor's JDBC driver, uploaded to the bridge (Nexus does not redistribute third-party drivers)
`username` / `password`	Database credentials, stored as named secrets in your tenant's Key Vault

The driver JAR upload is what makes the connector truly generic: because JDBC drivers are vendor-licensed and version-specific, you provide the exact driver your database and compliance posture require, rather than depending on whatever Nexus bundled. Credentials are never inlined into the connection URL in report or pipeline code — they resolve from Key Vault at query time.

The JDBC sidecar

JDBC is a JVM protocol, so JDBC traffic is handled by a co-deployed driver sidecar — a process that loads the driver and speaks the wire protocol on localhost, which the Nexus server communicates with locally. The sidecar is an opt-in deployment component: it must be enabled in your deployment configuration before any JDBC-based bridge (generic JDBC or NetSuite SuiteAnalytics Connect) will load. If the sidecar is not running, Nexus does not load the connector; other connectors are unaffected. Enabling it is a one-time deployment setting — see Updates & configuration.

Capabilities

Feature	Supported
Read	Yes
Write (SQL insert / update / delete)	Yes
Schema discovery	Yes — via JDBC catalog metadata
Filter pushdown (`where`)	Yes
Order / `DISTINCT` / `HAVING` pushdown	Yes
`GROUP BY` + aggregates (`SUM`/`COUNT`/`AVG`/`MIN`/`MAX`)	Yes
Joins, select expressions	Yes
Merge / upsert	Depends on the target dialect — not assumed across all JDBC sources

Because generic JDBC targets a genuine SQL engine, it pushes a full analytical query surface down to the source: filtering, ordering, grouping, aggregation, distinct, having, joins, and select expressions all execute in the database, not in Nexus. Filter operators map to standard SQL, and $expr passes a raw SQL fragment through (a trusted-author surface). The one capability Nexus does not assume uniformly is merge/upsert, because merge syntax differs sharply across dialects (MERGE, ON CONFLICT, INSERT ... ON DUPLICATE KEY) — where merge isn't available for your target, express upserts as explicit update-then-insert logic in a pipeline.

As with every connector, pushdown is layered under the correctness guarantee: if you use an operator or construct the driver/dialect can't accept, the engine re-applies that part of the query in memory over the returned rows rather than returning a wrong answer. See pushdown semantics.

Example: query a Snowflake warehouse

async def run(ctx):
    rows = await ctx.adapters.warehouse.read({
        "container": "SALES",
        "collection": "FCT_ORDERS",
        "where": {"order_date": {"$gte": "2026-01-01"}, "region": {"$eq": "EMEA"}},
        "group_by": ["region"],
        "select_expressions": ["region", "SUM(net_amount) AS revenue", "COUNT(*) AS orders"],
    })
    ctx.logger.info("EMEA revenue rows: %d", len(rows))
    return ctx.result(rows=rows)

The WHERE, GROUP BY, and aggregates all execute inside Snowflake; Nexus receives only the grouped result.

Relationship to NetSuite SuiteAnalytics Connect

The NetSuite SuiteAnalytics Connect connector is a specialized use of this same JDBC substrate. SuiteAnalytics Connect is Oracle's JDBC surface onto NetSuite; Nexus's native Connect adapter wraps it with NetSuite-specific behavior — deriving the TBA-signed JDBC password from your token-based-auth credentials, normalizing the account host, and unifying schema discovery with the REST adapter. It runs over the same driver sidecar the generic JDBC connector uses, and offers the same rich analytical SQL pushdown (window functions, CTEs, lateral joins, regex/JSON functions).

In other words: if you want NetSuite analytics, use the purpose-built SuiteAnalytics Connect connector, which handles the NetSuite-specific signing and discovery for you. If you have a different JDBC database, the generic JDBC connector gives you the same underlying capability with a driver and URL you supply. Both require the sidecar to be enabled.

What this does and doesn't do

It does turn any JDBC-speaking database into a full read/write/discover/pushdown Nexus bridge, using a driver you control.
It does push a complete analytical SQL surface down to the source.
It does not ship third-party drivers — you upload the vendor JAR.
It does not work until the JDBC sidecar is enabled in your deployment.
It does not assume merge/upsert across all dialects — verify it for your target or use pipeline logic.