From acf678b3888db44478fc5a8ca12183cee9c68a8d Mon Sep 17 00:00:00 2001 From: Pawel Kosiec Date: Thu, 2 Apr 2026 17:50:15 +0200 Subject: [PATCH 1/9] feat(lakebase): add deploy-first workflow guidance and schema permission docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document the deploy-first workflow to prevent the common permission error when running a Lakebase app locally before deploying. The SP has CONNECT_AND_CREATE permission and cannot access schemas created by other roles — deploying first ensures the SP owns the schema. Co-authored-by: Isaac --- manifest.json | 52 ++++--------------- .../references/appkit/lakebase.md | 25 ++++++++- skills/databricks-lakebase/SKILL.md | 9 ++++ 3 files changed, 42 insertions(+), 44 deletions(-) diff --git a/manifest.json b/manifest.json index ffd9ca8..a222ff5 100644 --- a/manifest.json +++ b/manifest.json @@ -1,17 +1,14 @@ { "version": "2", - "updated_at": "2026-04-07T12:45:02Z", + "updated_at": "2026-04-02T15:49:24Z", "skills": { "databricks-apps": { "version": "0.1.1", "description": "Databricks Apps development and deployment", "experimental": false, - "updated_at": "2026-04-07T12:41:53Z", + "updated_at": "2026-04-02T15:49:00Z", "files": [ "SKILL.md", - "agents/openai.yaml", - "assets/databricks.png", - "assets/databricks.svg", "references/appkit/appkit-sdk.md", "references/appkit/frontend.md", "references/appkit/lakebase.md", @@ -29,69 +26,40 @@ "version": "0.1.0", "description": "Core Databricks skill for CLI, auth, and data exploration", "experimental": false, - "updated_at": "2026-04-07T12:41:53Z", + "updated_at": "2026-04-02T14:44:18Z", "files": [ "SKILL.md", - "agents/openai.yaml", - "assets/databricks.png", - "assets/databricks.svg", "data-exploration.md", "databricks-cli-auth.md", - "databricks-cli-install.md" + "databricks-cli-install.md", + "declarative-automation-bundles.md" ] }, - "databricks-dabs": { - "version": "0.0.0", - "description": "Declarative Automation Bundles (DABs) for deploying and managing Databricks resources", - "experimental": false, - "updated_at": "2026-04-07T12:44:49Z", - "files": [ - "SKILL.md", - "agents/openai.yaml", - "assets/databricks.png", - "assets/databricks.svg", - "references/alerts.md", - "references/bundle-structure.md", - "references/deploy-and-run.md", - "references/resource-permissions.md", - "references/sdp-pipelines.md" - ], - "base_revision": "e742f36e8ab1" - }, "databricks-jobs": { "version": "0.1.0", "description": "Databricks Jobs orchestration and scheduling", "experimental": false, - "updated_at": "2026-04-07T12:41:53Z", + "updated_at": "2026-04-02T14:44:18Z", "files": [ - "SKILL.md", - "agents/openai.yaml", - "assets/databricks.png", - "assets/databricks.svg" + "SKILL.md" ] }, "databricks-lakebase": { "version": "0.1.0", "description": "Databricks Lakebase database development", "experimental": false, - "updated_at": "2026-04-07T12:41:53Z", + "updated_at": "2026-04-02T15:49:12Z", "files": [ - "SKILL.md", - "agents/openai.yaml", - "assets/databricks.png", - "assets/databricks.svg" + "SKILL.md" ] }, "databricks-pipelines": { "version": "0.1.0", "description": "Databricks Pipelines (DLT) for ETL and streaming", "experimental": false, - "updated_at": "2026-04-07T12:41:53Z", + "updated_at": "2026-04-02T14:44:18Z", "files": [ "SKILL.md", - "agents/openai.yaml", - "assets/databricks.png", - "assets/databricks.svg", "references/auto-cdc-python.md", "references/auto-cdc-sql.md", "references/auto-cdc.md", diff --git a/skills/databricks-apps/references/appkit/lakebase.md b/skills/databricks-apps/references/appkit/lakebase.md index d2679fa..b97fa92 100644 --- a/skills/databricks-apps/references/appkit/lakebase.md +++ b/skills/databricks-apps/references/appkit/lakebase.md @@ -134,7 +134,7 @@ export const appRouter = t.router({ ## Schema Initialization -**Always create a custom schema** — the Service Principal has `CONNECT_AND_CREATE` permission but **cannot access the `public` schema**. Initialize tables on server startup: +**Always create a custom schema** — the Service Principal has `CONNECT_AND_CREATE` permission, which means it can create new objects but **cannot access any existing schemas or tables** (including `public`). The SP must create the schema itself to become its owner. Initialize tables on server startup: ```typescript // server/server.ts — run once at startup before handling requests @@ -148,6 +148,23 @@ await pool.query(` `); ``` +## Deploy-First Workflow + +**ALWAYS deploy the app before running it locally.** This is the #1 source of Lakebase permission errors. + +When deployed, the app's Service Principal runs the schema initialization SQL above, creating the schema and tables — and becoming their **owner**. Only the owner (or a superuser) can access those objects. + +**If you run locally first**, your personal credentials create the schema and become the owner. The deployed Service Principal then **cannot access it** — even though it has `CONNECT_AND_CREATE` — because it didn't create it and cannot access existing schemas. + +**Correct workflow:** +1. **Deploy first**: `databricks apps deploy --profile ` — the SP creates and owns the schema +2. **Grant local access**: assign `databricks_superuser` to your identity via the Lakebase UI +3. **Develop locally**: your credentials get DML access (SELECT/INSERT/UPDATE/DELETE) to SP-owned schemas + +> **Note:** `databricks_superuser` grants full DML but **not DDL** (CREATE SCHEMA, CREATE TABLE) on SP-owned schemas. If you need to alter the schema during local development, redeploy the app to apply DDL changes. + +**If you already ran locally first** and hit `permission denied` after deploying: connect to the database with your credentials, drop the schema (`DROP SCHEMA CASCADE;`), then redeploy so the SP recreates it. + ## ORM Integration (Optional) The pool returned by `createLakebasePool()` is a standard `pg.Pool` — works with any PostgreSQL library: @@ -180,6 +197,8 @@ const prisma = new PrismaClient({ adapter }); ## Local Development +> **Important:** Deploy the app first so the Service Principal creates and owns the database schema. See **Deploy-First Workflow** above. If you run locally before deploying, you'll create schemas under your credentials that the SP cannot access after deployment. + The Lakebase env vars (`PGHOST`, `PGDATABASE`, etc.) are auto-set only when deployed. For local development, get the connection details from your endpoint and set them manually: ```bash @@ -206,7 +225,9 @@ Load `server/.env` in your dev server (e.g. via `dotenv` or `node --env-file=ser | Error | Cause | Solution | |-------|-------|---------| -| `permission denied for schema public` | Service Principal lacks access to `public` | Create custom schema: `CREATE SCHEMA IF NOT EXISTS app_data` | +| `permission denied for schema public` | SP cannot access `public` schema | Create custom schema: `CREATE SCHEMA IF NOT EXISTS app_data` and qualify all table names with `app_data.` | +| `permission denied for schema ` | Schema was created by another role (e.g. you ran locally before deploying) | Drop the schema, then redeploy so the SP creates and owns it. See **Deploy-First Workflow** above | +| Works locally but `permission denied` after deploy | Local credentials created the schema; the SP can't access schemas it doesn't own | Drop the schema, deploy first, then use `databricks_superuser` for local dev. See **Deploy-First Workflow** above | | `connection refused` | Pool not connected or wrong env vars | Check `PGHOST`, `PGPORT`, `LAKEBASE_ENDPOINT` are set | | `relation "X" does not exist` | Tables not initialized | Run `CREATE TABLE IF NOT EXISTS` at startup | | App builds but pool fails at runtime | Env vars not set locally | Set vars in `server/.env` — see Local Development above | diff --git a/skills/databricks-lakebase/SKILL.md b/skills/databricks-lakebase/SKILL.md index c00f4d3..af35aee 100644 --- a/skills/databricks-lakebase/SKILL.md +++ b/skills/databricks-lakebase/SKILL.md @@ -148,6 +148,14 @@ Where `` is the full resource name (e.g. `projects//bra For the full app development workflow, use the **`databricks-apps`** skill. +### Schema Permissions for Deployed Apps + +When a Lakebase database is used by a deployed Databricks App, the app's Service Principal has `CONNECT_AND_CREATE` permission. This means it can **create new schemas** but **cannot access schemas or tables created by other roles** (including `public`). + +**Deploy the app before running locally.** The deployed SP runs schema initialization (e.g. `CREATE SCHEMA IF NOT EXISTS app_data`) and becomes the schema owner. If you run locally first, your credentials create the schema — and the SP cannot access it after deployment. + +After deploying, grant `databricks_superuser` to your identity via the Lakebase UI for local DML access. See the **`databricks-apps`** skill's Lakebase guide for the full deploy-first workflow. + ### Other Workflows **Connect a Postgres client** @@ -178,5 +186,6 @@ databricks postgres create-endpoint projects//branches/ < |-------|----------| | `cannot configure default credentials` | Use `--profile` flag or authenticate first | | `PERMISSION_DENIED` | Check workspace permissions | +| `permission denied for schema ` | Schema owned by another role. Deploy the app first so the SP creates and owns the schema. See **Schema Permissions for Deployed Apps** above | | Protected branch cannot be deleted | `update-branch` to set `spec.is_protected` to `false` first | | Long-running operation timeout | Use `--no-wait` and poll with `get-operation` | From 9546a7cdb3644699987c475c0aad24785d0f53d0 Mon Sep 17 00:00:00 2001 From: Pawel Kosiec Date: Thu, 2 Apr 2026 19:54:01 +0200 Subject: [PATCH 2/9] refactor: move deploy-first workflow to databricks-lakebase skill The deploy-first workflow and schema permission docs are fundamentally about Lakebase's permission model, not AppKit specifically. Move the canonical content to databricks-lakebase/SKILL.md so it applies regardless of which app framework is used, and have the AppKit lakebase reference point there instead. Co-authored-by: Isaac --- manifest.json | 6 ++--- .../references/appkit/lakebase.md | 25 +++---------------- skills/databricks-lakebase/SKILL.md | 17 ++++++++++--- 3 files changed, 21 insertions(+), 27 deletions(-) diff --git a/manifest.json b/manifest.json index a222ff5..373e0f3 100644 --- a/manifest.json +++ b/manifest.json @@ -1,12 +1,12 @@ { "version": "2", - "updated_at": "2026-04-02T15:49:24Z", + "updated_at": "2026-04-02T17:53:54Z", "skills": { "databricks-apps": { "version": "0.1.1", "description": "Databricks Apps development and deployment", "experimental": false, - "updated_at": "2026-04-02T15:49:00Z", + "updated_at": "2026-04-02T17:53:44Z", "files": [ "SKILL.md", "references/appkit/appkit-sdk.md", @@ -48,7 +48,7 @@ "version": "0.1.0", "description": "Databricks Lakebase database development", "experimental": false, - "updated_at": "2026-04-02T15:49:12Z", + "updated_at": "2026-04-02T17:53:21Z", "files": [ "SKILL.md" ] diff --git a/skills/databricks-apps/references/appkit/lakebase.md b/skills/databricks-apps/references/appkit/lakebase.md index b97fa92..fa29cd4 100644 --- a/skills/databricks-apps/references/appkit/lakebase.md +++ b/skills/databricks-apps/references/appkit/lakebase.md @@ -134,7 +134,7 @@ export const appRouter = t.router({ ## Schema Initialization -**Always create a custom schema** — the Service Principal has `CONNECT_AND_CREATE` permission, which means it can create new objects but **cannot access any existing schemas or tables** (including `public`). The SP must create the schema itself to become its owner. Initialize tables on server startup: +**Always create a custom schema** — the Service Principal cannot access any existing schemas (including `public`). It must create the schema itself to become its owner. See **`databricks-lakebase`** skill's **Schema Permissions for Deployed Apps** for the full permission model and deploy-first workflow. Initialize tables on server startup: ```typescript // server/server.ts — run once at startup before handling requests @@ -148,23 +148,6 @@ await pool.query(` `); ``` -## Deploy-First Workflow - -**ALWAYS deploy the app before running it locally.** This is the #1 source of Lakebase permission errors. - -When deployed, the app's Service Principal runs the schema initialization SQL above, creating the schema and tables — and becoming their **owner**. Only the owner (or a superuser) can access those objects. - -**If you run locally first**, your personal credentials create the schema and become the owner. The deployed Service Principal then **cannot access it** — even though it has `CONNECT_AND_CREATE` — because it didn't create it and cannot access existing schemas. - -**Correct workflow:** -1. **Deploy first**: `databricks apps deploy --profile ` — the SP creates and owns the schema -2. **Grant local access**: assign `databricks_superuser` to your identity via the Lakebase UI -3. **Develop locally**: your credentials get DML access (SELECT/INSERT/UPDATE/DELETE) to SP-owned schemas - -> **Note:** `databricks_superuser` grants full DML but **not DDL** (CREATE SCHEMA, CREATE TABLE) on SP-owned schemas. If you need to alter the schema during local development, redeploy the app to apply DDL changes. - -**If you already ran locally first** and hit `permission denied` after deploying: connect to the database with your credentials, drop the schema (`DROP SCHEMA CASCADE;`), then redeploy so the SP recreates it. - ## ORM Integration (Optional) The pool returned by `createLakebasePool()` is a standard `pg.Pool` — works with any PostgreSQL library: @@ -197,7 +180,7 @@ const prisma = new PrismaClient({ adapter }); ## Local Development -> **Important:** Deploy the app first so the Service Principal creates and owns the database schema. See **Deploy-First Workflow** above. If you run locally before deploying, you'll create schemas under your credentials that the SP cannot access after deployment. +> **Important:** Deploy the app first so the Service Principal creates and owns the database schema. See **`databricks-lakebase`** skill's **Schema Permissions for Deployed Apps** for details. If you run locally before deploying, you'll create schemas under your credentials that the SP cannot access after deployment. The Lakebase env vars (`PGHOST`, `PGDATABASE`, etc.) are auto-set only when deployed. For local development, get the connection details from your endpoint and set them manually: @@ -226,8 +209,8 @@ Load `server/.env` in your dev server (e.g. via `dotenv` or `node --env-file=ser | Error | Cause | Solution | |-------|-------|---------| | `permission denied for schema public` | SP cannot access `public` schema | Create custom schema: `CREATE SCHEMA IF NOT EXISTS app_data` and qualify all table names with `app_data.` | -| `permission denied for schema ` | Schema was created by another role (e.g. you ran locally before deploying) | Drop the schema, then redeploy so the SP creates and owns it. See **Deploy-First Workflow** above | -| Works locally but `permission denied` after deploy | Local credentials created the schema; the SP can't access schemas it doesn't own | Drop the schema, deploy first, then use `databricks_superuser` for local dev. See **Deploy-First Workflow** above | +| `permission denied for schema ` | Schema was created by another role (e.g. you ran locally before deploying) | Drop the schema, then redeploy so the SP creates and owns it. See **`databricks-lakebase`** skill's **Schema Permissions for Deployed Apps** | +| Works locally but `permission denied` after deploy | Local credentials created the schema; the SP can't access schemas it doesn't own | Drop the schema, deploy first, then use `databricks_superuser` for local dev. See **`databricks-lakebase`** skill's **Schema Permissions for Deployed Apps** | | `connection refused` | Pool not connected or wrong env vars | Check `PGHOST`, `PGPORT`, `LAKEBASE_ENDPOINT` are set | | `relation "X" does not exist` | Tables not initialized | Run `CREATE TABLE IF NOT EXISTS` at startup | | App builds but pool fails at runtime | Env vars not set locally | Set vars in `server/.env` — see Local Development above | diff --git a/skills/databricks-lakebase/SKILL.md b/skills/databricks-lakebase/SKILL.md index af35aee..b5d9dd3 100644 --- a/skills/databricks-lakebase/SKILL.md +++ b/skills/databricks-lakebase/SKILL.md @@ -150,11 +150,22 @@ For the full app development workflow, use the **`databricks-apps`** skill. ### Schema Permissions for Deployed Apps -When a Lakebase database is used by a deployed Databricks App, the app's Service Principal has `CONNECT_AND_CREATE` permission. This means it can **create new schemas** but **cannot access schemas or tables created by other roles** (including `public`). +When a Lakebase database is used by a deployed Databricks App, the app's Service Principal has `CONNECT_AND_CREATE` permission, which means it can create new objects but **cannot access any existing schemas or tables** (including `public`). The SP must create the schema itself to become its owner. -**Deploy the app before running locally.** The deployed SP runs schema initialization (e.g. `CREATE SCHEMA IF NOT EXISTS app_data`) and becomes the schema owner. If you run locally first, your credentials create the schema — and the SP cannot access it after deployment. +**ALWAYS deploy the app before running it locally.** This is the #1 source of Lakebase permission errors. -After deploying, grant `databricks_superuser` to your identity via the Lakebase UI for local DML access. See the **`databricks-apps`** skill's Lakebase guide for the full deploy-first workflow. +When deployed, the app's Service Principal runs the schema initialization SQL (e.g. `CREATE SCHEMA IF NOT EXISTS app_data`), creating the schema and tables — and becoming their **owner**. Only the owner (or a superuser) can access those objects. + +**If you run locally first**, your personal credentials create the schema and become the owner. The deployed Service Principal then **cannot access it** — even though it has `CONNECT_AND_CREATE` — because it didn't create it and cannot access existing schemas. + +**Correct workflow:** +1. **Deploy first**: `databricks apps deploy --profile ` — the SP creates and owns the schema +2. **Grant local access**: assign `databricks_superuser` to your identity via the Lakebase UI +3. **Develop locally**: your credentials get DML access (SELECT/INSERT/UPDATE/DELETE) to SP-owned schemas + +> **Note:** `databricks_superuser` grants full DML but **not DDL** (CREATE SCHEMA, CREATE TABLE) on SP-owned schemas. If you need to alter the schema during local development, redeploy the app to apply DDL changes. + +**If you already ran locally first** and hit `permission denied` after deploying: connect to the database with your credentials, drop the schema (`DROP SCHEMA CASCADE;`), then redeploy so the SP recreates it. ### Other Workflows From d517895d2f9370ca305e9d3a0c6bad7bb7cf93c4 Mon Sep 17 00:00:00 2001 From: Pawel Kosiec Date: Thu, 2 Apr 2026 20:20:31 +0200 Subject: [PATCH 3/9] fix(lakebase): make deploy-first constraint more prominent in appkit reference Add deploy-first callout before Schema Initialization and strengthen Local Development warning to CRITICAL to prevent schema ownership issues. Co-authored-by: Isaac --- manifest.json | 2 +- skills/databricks-apps/references/appkit/lakebase.md | 4 +++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/manifest.json b/manifest.json index 373e0f3..a0f397b 100644 --- a/manifest.json +++ b/manifest.json @@ -1,6 +1,6 @@ { "version": "2", - "updated_at": "2026-04-02T17:53:54Z", + "updated_at": "2026-04-02T17:57:59Z", "skills": { "databricks-apps": { "version": "0.1.1", diff --git a/skills/databricks-apps/references/appkit/lakebase.md b/skills/databricks-apps/references/appkit/lakebase.md index fa29cd4..6227efd 100644 --- a/skills/databricks-apps/references/appkit/lakebase.md +++ b/skills/databricks-apps/references/appkit/lakebase.md @@ -132,6 +132,8 @@ export const appRouter = t.router({ }); ``` +> **Deploy first!** The Service Principal must create and own the schema. Run `databricks apps deploy` before any local development. See **`databricks-lakebase`** skill's **Schema Permissions for Deployed Apps** for details. + ## Schema Initialization **Always create a custom schema** — the Service Principal cannot access any existing schemas (including `public`). It must create the schema itself to become its owner. See **`databricks-lakebase`** skill's **Schema Permissions for Deployed Apps** for the full permission model and deploy-first workflow. Initialize tables on server startup: @@ -180,7 +182,7 @@ const prisma = new PrismaClient({ adapter }); ## Local Development -> **Important:** Deploy the app first so the Service Principal creates and owns the database schema. See **`databricks-lakebase`** skill's **Schema Permissions for Deployed Apps** for details. If you run locally before deploying, you'll create schemas under your credentials that the SP cannot access after deployment. +> **CRITICAL: Deploy the app first** so the Service Principal creates and owns the database schema. If you run locally before deploying, you'll create schemas under your credentials that the SP **cannot access** after deployment. See **`databricks-lakebase`** skill's **Schema Permissions for Deployed Apps** for the full workflow and recovery steps. The Lakebase env vars (`PGHOST`, `PGDATABASE`, etc.) are auto-set only when deployed. For local development, get the connection details from your endpoint and set them manually: From ecf3d1d1367154d17e66635044369aa45e11ea23 Mon Sep 17 00:00:00 2001 From: Pawel Kosiec Date: Thu, 2 Apr 2026 20:27:30 +0200 Subject: [PATCH 4/9] fix(lakebase): clarify databricks_superuser is only needed for non-project-creators Project creators already have sufficient access to SP-owned schemas; only other team members need the databricks_superuser role assignment. Co-authored-by: Isaac --- skills/databricks-lakebase/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/databricks-lakebase/SKILL.md b/skills/databricks-lakebase/SKILL.md index b5d9dd3..de29ecd 100644 --- a/skills/databricks-lakebase/SKILL.md +++ b/skills/databricks-lakebase/SKILL.md @@ -160,10 +160,10 @@ When deployed, the app's Service Principal runs the schema initialization SQL (e **Correct workflow:** 1. **Deploy first**: `databricks apps deploy --profile ` — the SP creates and owns the schema -2. **Grant local access**: assign `databricks_superuser` to your identity via the Lakebase UI +2. **Grant local access** *(if needed)*: if you're not the project creator, assign `databricks_superuser` to your identity via the Lakebase UI. Project creators already have sufficient access. 3. **Develop locally**: your credentials get DML access (SELECT/INSERT/UPDATE/DELETE) to SP-owned schemas -> **Note:** `databricks_superuser` grants full DML but **not DDL** (CREATE SCHEMA, CREATE TABLE) on SP-owned schemas. If you need to alter the schema during local development, redeploy the app to apply DDL changes. +> **Note:** Project creators already have access to SP-owned schemas. Other team members need `databricks_superuser` (grants full DML but **not DDL**). If you need to alter the schema during local development, redeploy the app to apply DDL changes. **If you already ran locally first** and hit `permission denied` after deploying: connect to the database with your credentials, drop the schema (`DROP SCHEMA CASCADE;`), then redeploy so the SP recreates it. From 7c40a60c409f7655593f7fdbabd4d20c8038efea Mon Sep 17 00:00:00 2001 From: Pawel Kosiec Date: Tue, 7 Apr 2026 12:30:01 +0200 Subject: [PATCH 5/9] fix(lakebase): ask user before dropping schema to prevent data loss Instead of unconditionally instructing agents to DROP SCHEMA CASCADE on permission errors, warn about data loss and ask the user how to proceed (drop vs. reassign ownership). Co-authored-by: Isaac --- skills/databricks-apps/references/appkit/lakebase.md | 4 ++-- skills/databricks-lakebase/SKILL.md | 4 +++- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/skills/databricks-apps/references/appkit/lakebase.md b/skills/databricks-apps/references/appkit/lakebase.md index 6227efd..2274e27 100644 --- a/skills/databricks-apps/references/appkit/lakebase.md +++ b/skills/databricks-apps/references/appkit/lakebase.md @@ -211,8 +211,8 @@ Load `server/.env` in your dev server (e.g. via `dotenv` or `node --env-file=ser | Error | Cause | Solution | |-------|-------|---------| | `permission denied for schema public` | SP cannot access `public` schema | Create custom schema: `CREATE SCHEMA IF NOT EXISTS app_data` and qualify all table names with `app_data.` | -| `permission denied for schema ` | Schema was created by another role (e.g. you ran locally before deploying) | Drop the schema, then redeploy so the SP creates and owns it. See **`databricks-lakebase`** skill's **Schema Permissions for Deployed Apps** | -| Works locally but `permission denied` after deploy | Local credentials created the schema; the SP can't access schemas it doesn't own | Drop the schema, deploy first, then use `databricks_superuser` for local dev. See **`databricks-lakebase`** skill's **Schema Permissions for Deployed Apps** | +| `permission denied for schema ` | Schema was created by another role (e.g. you ran locally before deploying) | **Ask the user before dropping** — `DROP SCHEMA` deletes all data. See **`databricks-lakebase`** skill's **Schema Permissions for Deployed Apps** for options | +| Works locally but `permission denied` after deploy | Local credentials created the schema; the SP can't access schemas it doesn't own | **Ask the user before dropping** — warn about data loss, then deploy first. See **`databricks-lakebase`** skill's **Schema Permissions for Deployed Apps** for options | | `connection refused` | Pool not connected or wrong env vars | Check `PGHOST`, `PGPORT`, `LAKEBASE_ENDPOINT` are set | | `relation "X" does not exist` | Tables not initialized | Run `CREATE TABLE IF NOT EXISTS` at startup | | App builds but pool fails at runtime | Env vars not set locally | Set vars in `server/.env` — see Local Development above | diff --git a/skills/databricks-lakebase/SKILL.md b/skills/databricks-lakebase/SKILL.md index de29ecd..bb1d085 100644 --- a/skills/databricks-lakebase/SKILL.md +++ b/skills/databricks-lakebase/SKILL.md @@ -165,7 +165,9 @@ When deployed, the app's Service Principal runs the schema initialization SQL (e > **Note:** Project creators already have access to SP-owned schemas. Other team members need `databricks_superuser` (grants full DML but **not DDL**). If you need to alter the schema during local development, redeploy the app to apply DDL changes. -**If you already ran locally first** and hit `permission denied` after deploying: connect to the database with your credentials, drop the schema (`DROP SCHEMA CASCADE;`), then redeploy so the SP recreates it. +**If you already ran locally first** and hit `permission denied` after deploying: the schema is owned by your personal credentials, not the SP. **⚠️ Do NOT drop the schema without asking the user first** — dropping it (`DROP SCHEMA CASCADE`) **deletes all data** in that schema. Ask the user how they'd like to proceed: +- **Option A (destructive):** Drop the schema and redeploy so the SP recreates it. Only safe if the schema has no valuable data. +- **Option B (manual):** The user can reassign ownership or manually grant the SP access, preserving existing data. ### Other Workflows From af9a86b6d46e0d9ee74e22fb9e65b09eb577efba Mon Sep 17 00:00:00 2001 From: Pawel Kosiec Date: Tue, 7 Apr 2026 12:40:54 +0200 Subject: [PATCH 6/9] fix(lakebase): use correct CAN_CONNECT_AND_CREATE permission name Co-authored-by: Isaac --- skills/databricks-lakebase/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/databricks-lakebase/SKILL.md b/skills/databricks-lakebase/SKILL.md index bb1d085..531179e 100644 --- a/skills/databricks-lakebase/SKILL.md +++ b/skills/databricks-lakebase/SKILL.md @@ -150,13 +150,13 @@ For the full app development workflow, use the **`databricks-apps`** skill. ### Schema Permissions for Deployed Apps -When a Lakebase database is used by a deployed Databricks App, the app's Service Principal has `CONNECT_AND_CREATE` permission, which means it can create new objects but **cannot access any existing schemas or tables** (including `public`). The SP must create the schema itself to become its owner. +When a Lakebase database is used by a deployed Databricks App, the app's Service Principal has `CAN_CONNECT_AND_CREATE` permission, which means it can create new objects but **cannot access any existing schemas or tables** (including `public`). The SP must create the schema itself to become its owner. **ALWAYS deploy the app before running it locally.** This is the #1 source of Lakebase permission errors. When deployed, the app's Service Principal runs the schema initialization SQL (e.g. `CREATE SCHEMA IF NOT EXISTS app_data`), creating the schema and tables — and becoming their **owner**. Only the owner (or a superuser) can access those objects. -**If you run locally first**, your personal credentials create the schema and become the owner. The deployed Service Principal then **cannot access it** — even though it has `CONNECT_AND_CREATE` — because it didn't create it and cannot access existing schemas. +**If you run locally first**, your personal credentials create the schema and become the owner. The deployed Service Principal then **cannot access it** — even though it has `CAN_CONNECT_AND_CREATE` — because it didn't create it and cannot access existing schemas. **Correct workflow:** 1. **Deploy first**: `databricks apps deploy --profile ` — the SP creates and owns the schema From addeade490b232151276f667785ac2f92525da43 Mon Sep 17 00:00:00 2001 From: Pawel Kosiec Date: Tue, 7 Apr 2026 13:07:54 +0200 Subject: [PATCH 7/9] fix(lakebase): clarify App+Lakebase scope and add deploy verification gate Address Arseni's review comments: - Clarify deploy-first guidance applies to App + Lakebase combo only - Replace passive CRITICAL callout with agent-executable verification step Co-authored-by: Isaac --- .../references/appkit/lakebase.md | 17 +++++++++++++++-- skills/databricks-lakebase/SKILL.md | 2 +- 2 files changed, 16 insertions(+), 3 deletions(-) diff --git a/skills/databricks-apps/references/appkit/lakebase.md b/skills/databricks-apps/references/appkit/lakebase.md index 2274e27..1ebc19d 100644 --- a/skills/databricks-apps/references/appkit/lakebase.md +++ b/skills/databricks-apps/references/appkit/lakebase.md @@ -132,7 +132,7 @@ export const appRouter = t.router({ }); ``` -> **Deploy first!** The Service Principal must create and own the schema. Run `databricks apps deploy` before any local development. See **`databricks-lakebase`** skill's **Schema Permissions for Deployed Apps** for details. +> **Deploy first (App + Lakebase only)!** When your Databricks App uses Lakebase, the Service Principal must create and own the schema. Run `databricks apps deploy` before any local development. See **`databricks-lakebase`** skill's **Schema Permissions for Deployed Apps** for details. ## Schema Initialization @@ -182,7 +182,20 @@ const prisma = new PrismaClient({ adapter }); ## Local Development -> **CRITICAL: Deploy the app first** so the Service Principal creates and owns the database schema. If you run locally before deploying, you'll create schemas under your credentials that the SP **cannot access** after deployment. See **`databricks-lakebase`** skill's **Schema Permissions for Deployed Apps** for the full workflow and recovery steps. +### Prerequisites (MUST verify before local development) + +**This applies when your Databricks App uses Lakebase.** Run this check before any local development: + +```bash +databricks apps get --profile +``` + +Check the response for the `active_deployment` field. If it exists with `status.state` of `SUCCEEDED`, the app has been deployed. If `active_deployment` is missing, the app has never been deployed: +1. **STOP** — do not proceed with local development +2. Deploy first: `databricks apps deploy --profile ` +3. Wait for deployment to complete, then continue + +If you skip this step, the Service Principal won't own the database schema. You'll create schemas under your credentials that the SP **cannot access** after deployment. See **`databricks-lakebase`** skill's **Schema Permissions for Deployed Apps** for the full workflow and recovery steps. The Lakebase env vars (`PGHOST`, `PGDATABASE`, etc.) are auto-set only when deployed. For local development, get the connection details from your endpoint and set them manually: diff --git a/skills/databricks-lakebase/SKILL.md b/skills/databricks-lakebase/SKILL.md index 531179e..b65502a 100644 --- a/skills/databricks-lakebase/SKILL.md +++ b/skills/databricks-lakebase/SKILL.md @@ -159,7 +159,7 @@ When deployed, the app's Service Principal runs the schema initialization SQL (e **If you run locally first**, your personal credentials create the schema and become the owner. The deployed Service Principal then **cannot access it** — even though it has `CAN_CONNECT_AND_CREATE` — because it didn't create it and cannot access existing schemas. **Correct workflow:** -1. **Deploy first**: `databricks apps deploy --profile ` — the SP creates and owns the schema +1. **Deploy first**: `databricks apps deploy --profile ` — verify with `databricks apps get --profile ` that the app is deployed before proceeding 2. **Grant local access** *(if needed)*: if you're not the project creator, assign `databricks_superuser` to your identity via the Lakebase UI. Project creators already have sufficient access. 3. **Develop locally**: your credentials get DML access (SELECT/INSERT/UPDATE/DELETE) to SP-owned schemas From 3c7716af9344494052406bb70a67d3aa8087a32d Mon Sep 17 00:00:00 2001 From: Pawel Kosiec Date: Tue, 7 Apr 2026 13:41:28 +0200 Subject: [PATCH 8/9] chore: regenerate manifest after rebase on main Picks up new databricks-dabs skill from main and updates timestamps. Co-authored-by: Isaac --- manifest.json | 29 +++++++++++++++++++++-------- 1 file changed, 21 insertions(+), 8 deletions(-) diff --git a/manifest.json b/manifest.json index a0f397b..9e124f2 100644 --- a/manifest.json +++ b/manifest.json @@ -1,12 +1,12 @@ { "version": "2", - "updated_at": "2026-04-02T17:57:59Z", + "updated_at": "2026-04-07T11:41:21Z", "skills": { "databricks-apps": { "version": "0.1.1", "description": "Databricks Apps development and deployment", "experimental": false, - "updated_at": "2026-04-02T17:53:44Z", + "updated_at": "2026-04-07T11:41:14Z", "files": [ "SKILL.md", "references/appkit/appkit-sdk.md", @@ -26,20 +26,33 @@ "version": "0.1.0", "description": "Core Databricks skill for CLI, auth, and data exploration", "experimental": false, - "updated_at": "2026-04-02T14:44:18Z", + "updated_at": "2026-04-07T11:41:02Z", "files": [ "SKILL.md", "data-exploration.md", "databricks-cli-auth.md", - "databricks-cli-install.md", - "declarative-automation-bundles.md" + "databricks-cli-install.md" + ] + }, + "databricks-dabs": { + "version": "0.0.0", + "description": "Declarative Automation Bundles (DABs) for deploying and managing Databricks resources", + "experimental": false, + "updated_at": "2026-04-07T11:41:02Z", + "files": [ + "SKILL.md", + "references/alerts.md", + "references/bundle-structure.md", + "references/deploy-and-run.md", + "references/resource-permissions.md", + "references/sdp-pipelines.md" ] }, "databricks-jobs": { "version": "0.1.0", "description": "Databricks Jobs orchestration and scheduling", "experimental": false, - "updated_at": "2026-04-02T14:44:18Z", + "updated_at": "2026-04-07T10:27:43Z", "files": [ "SKILL.md" ] @@ -48,7 +61,7 @@ "version": "0.1.0", "description": "Databricks Lakebase database development", "experimental": false, - "updated_at": "2026-04-02T17:53:21Z", + "updated_at": "2026-04-07T11:41:14Z", "files": [ "SKILL.md" ] @@ -57,7 +70,7 @@ "version": "0.1.0", "description": "Databricks Pipelines (DLT) for ETL and streaming", "experimental": false, - "updated_at": "2026-04-02T14:44:18Z", + "updated_at": "2026-04-07T10:27:43Z", "files": [ "SKILL.md", "references/auto-cdc-python.md", From f433b0c84396fe0fd8caef5eb4e410817407c646 Mon Sep 17 00:00:00 2001 From: Pawel Kosiec Date: Tue, 7 Apr 2026 15:18:11 +0200 Subject: [PATCH 9/9] chore: regenerate manifest after rebase on main Co-authored-by: Isaac --- manifest.json | 39 +++++++++++++++++++++++++++++---------- 1 file changed, 29 insertions(+), 10 deletions(-) diff --git a/manifest.json b/manifest.json index 9e124f2..1723b57 100644 --- a/manifest.json +++ b/manifest.json @@ -1,14 +1,17 @@ { "version": "2", - "updated_at": "2026-04-07T11:41:21Z", + "updated_at": "2026-04-07T13:18:03Z", "skills": { "databricks-apps": { "version": "0.1.1", "description": "Databricks Apps development and deployment", "experimental": false, - "updated_at": "2026-04-07T11:41:14Z", + "updated_at": "2026-04-07T13:17:59Z", "files": [ "SKILL.md", + "agents/openai.yaml", + "assets/databricks.png", + "assets/databricks.svg", "references/appkit/appkit-sdk.md", "references/appkit/frontend.md", "references/appkit/lakebase.md", @@ -26,9 +29,12 @@ "version": "0.1.0", "description": "Core Databricks skill for CLI, auth, and data exploration", "experimental": false, - "updated_at": "2026-04-07T11:41:02Z", + "updated_at": "2026-04-07T13:17:41Z", "files": [ "SKILL.md", + "agents/openai.yaml", + "assets/databricks.png", + "assets/databricks.svg", "data-exploration.md", "databricks-cli-auth.md", "databricks-cli-install.md" @@ -38,41 +44,54 @@ "version": "0.0.0", "description": "Declarative Automation Bundles (DABs) for deploying and managing Databricks resources", "experimental": false, - "updated_at": "2026-04-07T11:41:02Z", + "updated_at": "2026-04-07T13:17:41Z", "files": [ "SKILL.md", + "agents/openai.yaml", + "assets/databricks.png", + "assets/databricks.svg", "references/alerts.md", "references/bundle-structure.md", "references/deploy-and-run.md", "references/resource-permissions.md", "references/sdp-pipelines.md" - ] + ], + "base_revision": "e742f36e8ab1" }, "databricks-jobs": { "version": "0.1.0", "description": "Databricks Jobs orchestration and scheduling", "experimental": false, - "updated_at": "2026-04-07T10:27:43Z", + "updated_at": "2026-04-07T13:17:41Z", "files": [ - "SKILL.md" + "SKILL.md", + "agents/openai.yaml", + "assets/databricks.png", + "assets/databricks.svg" ] }, "databricks-lakebase": { "version": "0.1.0", "description": "Databricks Lakebase database development", "experimental": false, - "updated_at": "2026-04-07T11:41:14Z", + "updated_at": "2026-04-07T13:17:59Z", "files": [ - "SKILL.md" + "SKILL.md", + "agents/openai.yaml", + "assets/databricks.png", + "assets/databricks.svg" ] }, "databricks-pipelines": { "version": "0.1.0", "description": "Databricks Pipelines (DLT) for ETL and streaming", "experimental": false, - "updated_at": "2026-04-07T10:27:43Z", + "updated_at": "2026-04-07T13:17:41Z", "files": [ "SKILL.md", + "agents/openai.yaml", + "assets/databricks.png", + "assets/databricks.svg", "references/auto-cdc-python.md", "references/auto-cdc-sql.md", "references/auto-cdc.md",