Databricks Lakebase Integration Guide - For Launch Partners

Congratulations on being a Launch Partner for Databricks Lakebase.

This guide provides the integration requirements, supported authentication methods, and best practices for integrating the Partner product with Lakebase.

Following these steps ensures that the Partner integration is validated and production-ready.

Integration Checklist

As a launch partner, please ensure your integration meets the following requirements:

1. Use one of the Supported Connectors
2. Implement application_name with the connector
3. OAuth Authentication without manual intervention (Required by the End of the Year). In the interim, the integration can use basic authentication with Postgres Native roles.
4. Named Connector (Required by End of Year)
5. Partner documentation detailing the Lakebase Integration for joint customers to follow.

In addition to the above checklist items, please review the Lakebase Operational Topics section for details on differentiating Lakebase from standard PostgreSQL and working with catalog/table imports between Lakehouse and Lakebase.

Supported Connectors

Use one of the following connectors to connect with Lakebase:

• JDBC
• psql
• psycopg2 / psycopg3
• SQLAlchemy

User-Agent Telemetry

All connectors must set the application name parameter for the downstream joint customer Telemetry.

For JDBC drivers

The PostgreSQL JDBC driver must recognize early on that the server supports modern startup parameters to capture the UserAgent (ApplicationName) correctly in Databricks Lakebase.

Setting ASSUME_MIN_SERVER_VERSION tells the driver it's safe to send the application_name during connection setup, rather than deferring it until later.

PGProperty.ASSUME_MIN_SERVER_VERSION.set(props, "9.1");

Without the setting, the JDBC driver sets application_name only after it establishes the connection, so telemetry cannot capture it.

With the setting, the JDBC driver includes the application_name in the startup packet, which is visible in logs and downstream metrics.

When setting the application_name in the JDBC connection string, the parameter is typically ApplicationName (in CamelCase). Some driver versions may vary; therefore, please refer to your JDBC driver version-specific documentation for details.

The application_name can also be set programmatically using PGProperty and is the recommended way for Partners.

For Other Connectors

The psql, psycopg, and SQLAlchemy parameter is application_name (all lowercase).

Format

Here is an example string to be set by the ISV Partner product for Lakebase integration:

ISVApplicationName = <isv-name+lakebase>

Examples

JDBC

String jdbcUrl = "jdbc:postgresql://instance-<instance>.database.cloud.databricks.com:5432/<dbname>";

// Set up connection properties
Properties props = new Properties();
PGProperty.USER.set(props, "<email>");
PGProperty.PASSWORD.set(props, "<OAuth token>");
PGProperty.APPLICATION_NAME.set(props, ISVApplicationName);
PGProperty.ASSUME_MIN_SERVER_VERSION.set(props, "9.1");
PGProperty.SSL.set(props, "require");

Connection conn = DriverManager.getConnection(jdbcUrl, props);

psql CLI

psql "host=instance-*** user=*** dbname=*** port=5432 sslmode=require application_name=ISVApplicationName"

psycopg2 (Python)

conn = psycopg2.connect(
    host="instance-***",
    port=5432,
    dbname="dbname",
    user="user",
    password="<OAuth token>",
    application_name="ISVApplicationName"
)

SQLAlchemy (Python)

create_engine(
    "postgresql+psycopg2://user:<OAuth token>@host:5432/dbname?application_name=ISVApplicationName"
)

Validation

To confirm that the integration is passing the application_name/ApplicationName correctly, run the following query in the Databricks Query Editor connected to Lakebase while the Partner product has active connections.

The query below will display all active connections and their associated application_name values.

SELECT pid,
       usename,
       client_addr,
       application_name,
       state,
       query
FROM pg_stat_activity
ORDER BY application_name;

Optionally, if the partner application closes connections quickly (e.g., millisecond queries or no persistent pool), the connection may not appear in pg_stat_activity. In such cases, and only if the product supports executing SQL, run a long-running query (like the one below) from the product to keep the session active long enough for validation.

SELECT COUNT(*)
FROM generate_series(1,100000) a
CROSS JOIN generate_series(1,100000) b;

Authentication Methods

Option 1: OAuth Authentication (Preferred; Required by EOY)

PostgreSQL does not natively support OAuth; however, Lakebase supports BYOT (Bring Your Own Token).

As a result, the application/client must manage the full token lifecycle (generation, refresh, and handoff).

The ISV Partner application must:

1. Obtain the OAuth token from Databricks via SDK or API.
2. Pass the token to the PostgreSQL connector during connection setup.
3. Handle token refresh as part of the connection logic.

In practice, the Partner application/client must implement OAuth flows similar to IDP-based token generation and hand them off to Lakebase (Token Federation logic).

For any questions related to OAuth implementation, please use the contact form in the Databricks Partner Portal.

Option 2: Role-Based Authentication

Use Postgres-native roles and grants.

Guidelines to create Postgres Native Roles:

1. Create Postgres-native role

CREATE ROLE lbaseadmin1 LOGIN PASSWORD '<your-secure-password>';

2. Individual grants to the Postgres-native role on the needed schemas

GRANT USAGE ON SCHEMA my_schema TO lbaseadmin1;
GRANT SELECT ON ALL TABLES IN SCHEMA my_schema TO lbaseadmin1;
-- For the Future tables that are going to be created in the schema
ALTER DEFAULT PRIVILEGES IN SCHEMA my_schema GRANT SELECT ON TABLES TO lbaseadmin1;

OR

3. Bulk grant across all non-system schemas in the current Lakebase database/catalog

DO $$
DECLARE r RECORD;
BEGIN
    FOR r IN
        SELECT schema_name
        FROM information_schema.schemata
        WHERE schema_name NOT IN ('pg_catalog','information_schema','pg_toast','__db_system')
    LOOP
        BEGIN
            EXECUTE format('GRANT USAGE ON SCHEMA %I TO lbaseadmin1;', r.schema_name);
            EXECUTE format('GRANT SELECT ON ALL TABLES IN SCHEMA %I TO lbaseadmin1;', r.schema_name);
            EXECUTE format('ALTER DEFAULT PRIVILEGES IN SCHEMA %I GRANT SELECT ON TABLES TO lbaseadmin1;', r.schema_name);
        EXCEPTION WHEN insufficient_privilege THEN
            RAISE NOTICE 'Skipped schema %', r.schema_name;
        END;
    END LOOP;
END
$$;

Named Connector

Why a Lakebase Named Connector?

1. OAuth Flows

As stated above, Postgres doesn't natively support OAuth, and thus, the Lakebase connector flow will differ from a regular PostgreSQL connection due to OAuth requirements.

The Partner product UI must request the end user to provide details for either:

• Client Credentials flow (M2M / service principal): For client ID and secret.
• Interactive flow (U2M): For OAuth app details

Please plan to add these options to the Lakebase named connector UI by EoY.

2. JDBC Configuration for Telemetry

To ensure the application_name (UserAgent) is captured correctly in downstream telemetry, the connector should include the following JDBC configuration:

PGProperty.ASSUME_MIN_SERVER_VERSION.set(props, "9.1");

This configuration is specific to Databricks Lakebase and might not be needed when connecting to generic PostgreSQL databases.

Including it in the Lakebase Named Connector ensures accurate telemetry for Lakebase connections without affecting integrations with other Postgres-compatible systems.

Please use the contact form in the Databricks Partner Portal to request Lakebase logos for the Named connector.

Lakebase Operational Topics

Differentiating Lakebase from Standard PostgreSQL

If the partner application needs to differentiate Lakebase from standard PostgreSQL in an effort to choose a different code path for Lakebase, these are the options:

• Run the SHOW shared_preload_libraries command and check for neon and databricks_auth in the output.

• Or check whether the hostname contains Lakebase-specific patterns

For example:

AWS:   instance-XXXXXXXX.database.cloud.databricks.com
Azure: instance-XXXXXXX.database.azuredatabricks.net

Catalog/Table Imports from Lakehouse to Lakebase

There is a SYNC TABLE capability that can move data from the Lakehouse into Lakebase (Postgres) tables for OLTP-serving workloads.

At a high level:

• A Primary Key is required to identify unique rows in the target Lakebase table.
• After syncing, the system creates a corresponding foreign catalog in the Lakehouse referencing the Lakebase destination.
• These synced objects appear as foreign tables in the Lakehouse, and you can query them like any other foreign source.

Additional notes:

• Synced data relies on declarative pipelines. Partners can automate pipeline creation and management via the Databricks API or SDK.
• Foreign catalogs created through sync are fully integrated into the Lakehouse governance model, enabling unified access control, lineage tracking, and auditing.

Catalog/Table Imports from Lakebase to Lakehouse

Importing from Lakebase to the Lakehouse is currently in Private Preview. Partners may:

• Request access through the Databricks Partner Portal to explore this capability.
• Evaluate how Lakebase-linked catalogs participate in Lakehouse governance workflows.