Skip to main content

Lakebase integrations

Lakebase integrations support three access methods: Lakebase Management APIs, the Lakebase Data API (REST), and SQL connectors over Postgres. User-Agent telemetry is captured via the HTTP User-Agent header for Management/Data APIs or the application_name field for SQL connections.

Lakebase access methods​

Lakebase Autoscaling supports the following access methods:

  • Lakebase Management APIs (/api/2.0/postgres/*): For partners that provision or manage Lakebase Autoscaling instances programmatically.
  • Lakebase Data API (HTTP/REST): Recommended for web applications, microservices, serverless functions, and third-party integrations. This option treats Lakebase as a Databricks-native operational store exposed over HTTPS.
  • SQL connectors over Postgres (TCP): Use JDBC, psql, psycopg2/3, or SQLAlchemy when full SQL semantics or advanced workflows are required (for example, schema initialization, migrations, or complex SQL queries).

Lakebase Management APIs​

Partners that provision or manage Lakebase Autoscaling instances must use the Lakebase Management APIs (/api/2.0/postgres/*).

Set the User-Agent HTTP header to identify your product when calling these APIs. For configuration details and examples, see REST APIs.

Lakebase Data API​

For the Lakebase Data API (REST), set the User-Agent HTTP header to identify your product in every request.

For User-Agent configuration details and code examples, see REST APIs.

SQL connectors​

For SQL-based access, use one of the following PostgreSQL-compatible connectors:

  • JDBC
  • psql
  • psycopg2 / psycopg3
  • SQLAlchemy

Postgres JDBC driver​

The PostgreSQL JDBC driver must detect that the Lakebase server supports modern startup parameters so it can send the User-Agent (Application_Name) correctly during the initial connection.

Set ASSUME_MIN_SERVER_VERSION so the driver treats the server as a newer PostgreSQL version and includes Application_Name in the startup packet. Without this setting, some clients send Application_Name later in the session, which breaks telemetry.

important

Setting ASSUME_MIN_SERVER_VERSION (for example, to 9.1) ensures the application name is sent upfront in the startup packet.

When using a connection string, the parameter name is typically ApplicationName (camelCase) or Application_Name, although it may vary by driver version. Verify the exact parameter name in the JDBC driver's documentation.

Partners must set it programmatically using PGProperty:

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, "<isv-name_product-name>/<product-version>");
PGProperty.ASSUME_MIN_SERVER_VERSION.set(props, "9.1");
PGProperty.SSL.set(props, "require");

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

Other integrations​

For psql, psycopg, and SQLAlchemy, the application_name parameter (all lowercase) is set at connection time and remains in effect for the entire session.

Set the application name using the format:

<isv-name_product-name>/<product-version>

psql client​

psql "host=instance-*** user=*** dbname=*** port=5432 sslmode=require application_name=<isv-name_product-name>/<product-version>"

psycopg2/3 (Python)​

conn = psycopg2.connect(
    host="instance-***",
    port=5432,
    dbname="dbname",
    user="user",
    password="<OAuth token>",
    application_name="<isv-name_product-name>/<product-version>"
)

SQLAlchemy (Python)​

from sqlalchemy import create_engine

engine = create_engine(
    "postgresql+psycopg2://user:<OAuth token>@host:5432/dbname"
    "?application_name=<isv-name_product-name>/<product-version>"
)

Validating your implementation​

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

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

This query displays all active connections and their associated application_name values.

note

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, run a long-running query 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;

What's next​

  • Connect to Lakebase: Learn about connection methods, authentication, and client tools. See Connect to your database.
  • Review User-Agent format: Understand the required format and guidelines.
  • Configure REST API telemetry: Set up User-Agent headers for Lakebase Management and Data APIs. See REST APIs.
  • Learn about Lakebase integration patterns: See OLTP (Lakebase) for authentication and operational guidance.