diff --git a/knowledge_base/app_with_database/README.md b/knowledge_base/app_with_database/README.md index 3b5c49d7..9cc35e92 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.4.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.