From 68de4e15ea88a347562ddb7210afef915be51b17 Mon Sep 17 00:00:00 2001 From: Jan Rose Date: Wed, 1 Jul 2026 08:50:44 +0200 Subject: [PATCH 1/2] Migrate Lakebase bundle examples to Postgres projects MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update both knowledge_base Lakebase examples from the legacy database_instances / database_catalogs resources to the Lakebase Autoscaling postgres_projects / postgres_catalogs resources, and refresh their READMEs (terminology, `databricks psql --project`, CLI v1.0.0). In app_with_database, declare the Postgres database explicitly via a postgres_databases resource (with an owner postgres_roles) so the app can reference it by a stable id. Relying on the catalog's create_database_if_missing creates a database with an auto-generated database_id that the app cannot address by path, so the app's postgres resource now points at ${resources.postgres_databases.my_database.id}. Verified end-to-end on staging: the bundle deploys, the app starts and provisions its schema and demo data, and `databricks bundle destroy` tears everything down. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- knowledge_base/app_with_database/README.md | 17 +++++----- .../app_with_database/resources/myapp.app.yml | 6 ++-- .../resources/mydb.database.yml | 11 ------ .../resources/mydb.postgres.yml | 34 +++++++++++++++++++ .../database_with_catalog/README.md | 21 ++++++------ .../database_with_catalog/databricks.yml | 19 ++++++----- 6 files changed, 67 insertions(+), 41 deletions(-) delete mode 100644 knowledge_base/app_with_database/resources/mydb.database.yml create mode 100644 knowledge_base/app_with_database/resources/mydb.postgres.yml diff --git a/knowledge_base/app_with_database/README.md b/knowledge_base/app_with_database/README.md index 3b5c49d7..86172867 100644 --- a/knowledge_base/app_with_database/README.md +++ b/knowledge_base/app_with_database/README.md @@ -1,17 +1,18 @@ # Databricks app with OLTP database This example demonstrates how to define a Databricks app backed by -an OLTP Postgres in a bundle. +a Lakebase Autoscaling Postgres database in a bundle. -It includes and deploys an example application that uses Python and Dash and a database instance. -When application is started it provisions its own schema and demonstration data in the OLTP database. +It includes and deploys an example application that uses Python and Dash and a Lakebase database project. +When application is started it provisions its own schema and demonstration data in the Postgres database. For more information about Databricks Apps see the [documentation](https://docs.databricks.com/aws/en/dev-tools/databricks-apps). -For more information about Databricks database instances see the [documentation](https://docs.databricks.com/aws/en/oltp/). +For more information about Lakebase see the [documentation](https://docs.databricks.com/aws/en/oltp/). +For more information about managing Lakebase with bundles see the [documentation](https://docs.databricks.com/aws/en/oltp/projects/manage-with-bundles). ## Prerequisites -* Databricks CLI v0.267.0 or above +* Databricks CLI v1.0.0 or above ## Usage @@ -19,7 +20,7 @@ For more information about Databricks database instances see the [documentation] ``` databricks bundle deploy -t dev ``` -Please note that after this bundle gets deployed, the database instance starts running immediately, which incurs cost. +Please note that after this bundle is deployed, the Lakebase project is created and incurs cost while running. Lakebase Autoscaling scales its compute down to zero when idle. 2. Run the app: ``` @@ -38,7 +39,7 @@ Alternatively, run `databricks bundle summary` to display its URL. Run the following command to display the data generated by the app: ``` -databricks psql example-database-instance -- --dbname example_database -c "select * from holidays.holiday_requests" +databricks psql --project example-database -- --dbname example_database -c "select * from holidays.holiday_requests" ``` 5. Explore the app data: @@ -48,7 +49,7 @@ databricks bundle open my_catalog ``` ## Clean up -To remove the provisioned resources run +To remove the deployed resources run ``` databricks bundle destroy ``` diff --git a/knowledge_base/app_with_database/resources/myapp.app.yml b/knowledge_base/app_with_database/resources/myapp.app.yml index 69512c0f..98647cfe 100644 --- a/knowledge_base/app_with_database/resources/myapp.app.yml +++ b/knowledge_base/app_with_database/resources/myapp.app.yml @@ -8,7 +8,7 @@ resources: resources: - name: "app-db" description: "A database for the app to be able to connect to and query" - database: - database_name: ${resources.database_catalogs.my_catalog.database_name} - instance_name: ${resources.database_catalogs.my_catalog.database_instance_name} + postgres: + branch: ${resources.postgres_projects.my_project.id}/branches/production + database: ${resources.postgres_databases.my_database.id} permission: "CAN_CONNECT_AND_CREATE" diff --git a/knowledge_base/app_with_database/resources/mydb.database.yml b/knowledge_base/app_with_database/resources/mydb.database.yml deleted file mode 100644 index 5cabcc68..00000000 --- a/knowledge_base/app_with_database/resources/mydb.database.yml +++ /dev/null @@ -1,11 +0,0 @@ -resources: - database_instances: - my_instance: - name: example-database-instance - capacity: CU_1 - database_catalogs: - my_catalog: - database_instance_name: ${resources.database_instances.my_instance.name} - database_name: "example_database" - name: example_database_catalog - create_database_if_not_exists: true diff --git a/knowledge_base/app_with_database/resources/mydb.postgres.yml b/knowledge_base/app_with_database/resources/mydb.postgres.yml new file mode 100644 index 00000000..efd15878 --- /dev/null +++ b/knowledge_base/app_with_database/resources/mydb.postgres.yml @@ -0,0 +1,34 @@ +resources: + postgres_projects: + my_project: + project_id: example-database + display_name: "Example app database" + pg_version: 16 + + # An owner role for the database. Lakebase requires a role when creating a + # database, and declaring it explicitly keeps the bundle portable across users + # (the auto-created project-owner role's id is derived from the creator's + # identity). + postgres_roles: + my_role: + parent: ${resources.postgres_projects.my_project.id}/branches/production + role_id: app-owner + postgres_role: app_owner + + # Declare the database explicitly so it has a stable id that the app can + # reference. Relying on the catalog's create_database_if_missing would create a + # database with an auto-generated id, which the app cannot reference by path. + postgres_databases: + my_database: + parent: ${resources.postgres_projects.my_project.id}/branches/production + database_id: example-database + postgres_database: example_database + role: ${resources.postgres_roles.my_role.id} + + # A Unity Catalog catalog backed by the Postgres database, so its data can be + # browsed in Unity Catalog. + postgres_catalogs: + my_catalog: + catalog_id: example_database_catalog + branch: ${resources.postgres_projects.my_project.id}/branches/production + postgres_database: ${resources.postgres_databases.my_database.postgres_database} diff --git a/knowledge_base/database_with_catalog/README.md b/knowledge_base/database_with_catalog/README.md index 91204119..027e2007 100644 --- a/knowledge_base/database_with_catalog/README.md +++ b/knowledge_base/database_with_catalog/README.md @@ -1,14 +1,15 @@ -# OLTP database instance with a catalog +# Lakebase database project with a catalog -This Declarative Automation Bundles example demonstrates how to define an OLTP database instance and a database catalog. +This Declarative Automation Bundles example demonstrates how to define a Lakebase Autoscaling database project and a Unity Catalog catalog backed by it. -It includes and deploys an example database instance and a catalog. When data changes in the database instance, they are reflected in Unity Catalog. +It includes and deploys an example project and a catalog. When data changes in the project's Postgres database, it is reflected in Unity Catalog. -For more information about Databricks database instances, see the [documentation](https://docs.databricks.com/aws/en/oltp/). +For more information about Lakebase, see the [documentation](https://docs.databricks.com/aws/en/oltp/). +For more information about managing Lakebase with bundles, see the [documentation](https://docs.databricks.com/aws/en/oltp/projects/manage-with-bundles). ## Prerequisites -* Databricks CLI v0.265.0 or above +* Databricks CLI v1.0.0 or above * `psql` client version 14 or above (only needed to run the demo data generation) ## Usage @@ -18,23 +19,23 @@ Modify `databricks.yml`: Run `databricks bundle deploy` to deploy the bundle. -Please note that after this bundle gets deployed, the database instance starts running, which incurs cost. +Please note that after this bundle is deployed, the Lakebase project is created and incurs cost while running. Lakebase Autoscaling scales its compute down to zero when idle. Run the following queries to populate your database with sample data: ```bash # Create a demo table: -databricks psql my-instance -- -d my_database -c "CREATE TABLE IF NOT EXISTS hello_world (id SERIAL PRIMARY KEY, message TEXT, number INTEGER, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP);" +databricks psql --project my-project -- -d my_database -c "CREATE TABLE IF NOT EXISTS hello_world (id SERIAL PRIMARY KEY, message TEXT, number INTEGER, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP);" # Insert 100 rows of demo data: -databricks psql my-instance -- -d my_database -c "INSERT INTO hello_world (message, number) SELECT 'Hello World #' || generate_series, generate_series FROM generate_series(1, 100);" +databricks psql --project my-project -- -d my_database -c "INSERT INTO hello_world (message, number) SELECT 'Hello World #' || generate_series, generate_series FROM generate_series(1, 100);" # Show generated rows: -databricks psql my-instance -- -d my_database -c "SELECT * FROM hello_world;" +databricks psql --project my-project -- -d my_database -c "SELECT * FROM hello_world;" ``` Open your catalog in Databricks: `databricks bundle open my_catalog` Navigate to the `public` schema, then to the `hello_world` table, then to "Sample data" and explore your generated data. ## Clean up -To remove the provisioned instance and catalog run `databricks bundle destroy` \ No newline at end of file +To remove the project and catalog run `databricks bundle destroy` \ No newline at end of file diff --git a/knowledge_base/database_with_catalog/databricks.yml b/knowledge_base/database_with_catalog/databricks.yml index b4830d92..927200e3 100644 --- a/knowledge_base/database_with_catalog/databricks.yml +++ b/knowledge_base/database_with_catalog/databricks.yml @@ -5,16 +5,17 @@ bundle: # host: https://myworkspace.cloud.databricks.com resources: - database_instances: - my_instance: - name: my-instance - capacity: CU_1 - database_catalogs: + postgres_projects: + my_project: + project_id: my-project + display_name: "Example project" + pg_version: 16 + postgres_catalogs: my_catalog: - database_instance_name: ${resources.database_instances.my_instance.name} - name: example_catalog - database_name: my_database - create_database_if_not_exists: true + catalog_id: example_catalog + branch: ${resources.postgres_projects.my_project.id}/branches/production + postgres_database: my_database + create_database_if_missing: true # Defines the targets for this bundle. From 2511b90831aa5e3358e5741e779fc94b17546e85 Mon Sep 17 00:00:00 2001 From: Jan Rose Date: Wed, 1 Jul 2026 08:56:33 +0200 Subject: [PATCH 2/2] app_with_database: require Databricks CLI v1.4.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The postgres_databases and postgres_roles resources this example now uses first shipped in Databricks CLI v1.4.0 (databricks/cli#5467 and databricks/cli#5627), so v1.0.0 is too low. database_with_catalog keeps v1.0.0, since postgres_catalogs shipped in v1.0.0. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- knowledge_base/app_with_database/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/knowledge_base/app_with_database/README.md b/knowledge_base/app_with_database/README.md index 86172867..9cc35e92 100644 --- a/knowledge_base/app_with_database/README.md +++ b/knowledge_base/app_with_database/README.md @@ -12,7 +12,7 @@ For more information about managing Lakebase with bundles see the [documentation ## Prerequisites -* Databricks CLI v1.0.0 or above +* Databricks CLI v1.4.0 or above ## Usage