Del via

Add a Lakebase resource to a Databricks app

Add Lakebase databases 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.

The following types of Lakebase database resources are available:

  • Lakebase Autoscaling: Organizes resources as projects containing branches and databases.
  • Lakebase Provisioned: Organizes resources as database instances.

Both types use the same PostgreSQL connection model and provide the same environment variables to your app.

Add a database resource

Before you add a Lakebase database as a resource, review the app resource prerequisites.

Lakebase Autoscaling

  1. When you create or edit an app, go to the Configure step.
  2. In the App resources section, click + Add resource.
  3. For resource type, select Database.
  4. Choose a project, branch, and database.
  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 postgres.

You must have CAN MANAGE permission on the Lakebase project to add it as an app resource.

Lakebase Provisioned

Note

You can't create new Provisioned databases after March 12, 2026, but you can add existing ones as app resources. See Autoscaling by default.

  1. When you create or edit an app, navigate to the Configure step.
  2. In the App resources section, click + Add resource.
  3. Select Database as the resource type.
  4. Choose a database instance.
  5. Choose a database within that instance.
  6. Select the appropriate permission level for your app. Currently, the only available permission is Can connect and create.
  7. (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:

  • Azure Databricks creates a PostgreSQL role in the selected database. The role name matches the service principal's client ID. If the role already exists, Azure Databricks reuses it.
  • Azure 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.
  • For Lakebase Autoscaling, the user adding the resource must have CAN MANAGE permission on the project.

Environment variables

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

If your app uses multiple PostgreSQL databases, these variables only reflect the first one. Use valueFrom with the resource key to retrieve the connection details for 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:

Your permissions Role in database? Result
CAN MANAGE Yes Azure Databricks reassigns all objects owned by the service principal to you and deletes the service principal's role.
CAN MANAGE No Azure 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 Azure 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, Azure 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.
  • Last updated on