Add a Lakebase resource to a Databricks app

Add Lakebase database instances as Databricks Apps resources to persist data across deployments. These PostgreSQL-backed resources let your app create and manage schemas and tables that retain state.

Preview

Lakebase database instances are in Public Preview. Your workspace admin must enable them before you can add them as an app resource.

Add a database resource

Before you can add a Lakebase database instance as an app resource, check that you meet the prerequisites.

Follow the steps in Add resources to a Databricks app to add a database resource.

1. In the App resources section when you create or edit an app, click + Add resource.
2. Select Database as the resource type.
3. Choose a database instance.
4. Choose a database within that instance.
5. Select the appropriate permission level for your app. Currently, the only available permission is Can connect and create.
6. (Optional) Specify a custom resource key, which is how you reference the database in your app configuration. The default key is database.

When you add a database resource:

• Databricks creates a PostgreSQL role in the selected database instance. The role name matches the service principal's client ID. If the role already exists, Databricks reuses it.
• Databricks grants the service principal CONNECT and CREATE privileges on the selected database. These privileges let the app create schemas and tables in the database.

Environment variables

When you deploy an app with a database resource, Databricks sets the following environment variables for the first database resource.

If your app uses multiple databases, these variables only reflect the first one. Use valueFrom with the resource key to retrieve the hostname of the database. See Use environment variables to access resources.

Variable	Description
PGAPPNAME	App name
PGDATABASE	Name of the database
PGHOST	Host name of the PostgreSQL server
PGPORT	Port for the PostgreSQL server
PGSSLMODE	SSL mode for the connection
PGUSER	Service principal's client ID and role name

Remove a database resource

If you remove database resources from an app, the app attempts to reassign all objects owned by the service principal to the user removing the resource.

The logic that the app uses primarily depends on whether you have a role in the database instance:

Your permissions	Role in database instance?	Result
CAN MANAGE	Yes	Databricks reassigns all objects owned by the service principal to you and deletes the service principal's role.
CAN MANAGE	No	Databricks creates a role for you, reassigns all objects owned by the service principal’s role to you, and deletes the service principal’s role.
No CAN MANAGE	N/A	Databricks removes the resource, but does not delete the role or reassign ownership. A warning appears in the UI, and you must manually clean up the role and owned objects later.

Notes

Consider the following when you add databases as app resources:

• If you revoke CONNECT and CREATE from one database and grant them on another in the same update, Databricks updates the privileges but doesn't recreate the service principal's role.
• Databases persist state. Any schemas or tables created by an app remain even after you re-deploy or stop the app.