docs(lakebase-autoscale): fold migration skill in as references/migration.md#525
Conversation
…ration.md Per Quentin's review on PR databricks-solutions#513: rather than ship a standalone databricks-lakebase-migration skill, fold the content into the existing databricks-lakebase-autoscale skill as a reference file. ("we already have too many skills.") Adds: - references/migration.md (304 lines, gpt-5.5-densified from PR databricks-solutions#513's 447-line SKILL.md). Preserves the five gotchas verbatim: 1. Raw CREATE DATABASE skips databricks_auth + neon extensions 2. App SP roles need databricks_create_role(), not CREATE ROLE 3. pg_restore --role=<sp-uuid> is required for SP ownership 4. Bundle deploy can't change database.instance_name; use databricks apps update --json with full resources array 5. UC sync pipelines don't auto-follow re-pointed apps; sync_* data is a frozen snapshot Also keeps: cosmetic-warning policy during pg_restore, common-issues table, Provisioned ↔ Autoscaling capacity mapping (with the 1 CU unit redefinition note: Provisioned 16 GB vs Autoscaling 2 GB). Updates SKILL.md: - Trigger description appends "or migrating an existing Lakebase Provisioned database to Autoscaling via pg_dump/pg_restore" - Reference Files section lists the new migration.md - Current Limitations clarifies that the snapshot migration path IS documented in this skill (was previously listed as a flat limitation with no recipe) PR databricks-solutions#513 to be closed pointing at this PR. Co-authored-by: Isaac
There was a problem hiding this comment.
Folding migration into autoscale as references/migration.md is the right call, keeps the five non-obvious gotchas (databricks_auth/neon extensions, databricks_create_role, pg_restore --role, bundle deploy instance_name limitation, sync_* pipelines not auto-following) without spawning a new skill. Mixed layout (core docs at root, migration in references/) is fine — reads as "this is the recipe you reach for once," matching the one-time nature of migration.
|
@dgokeeffe Now that #488 is merged, the SKILL.md conflict here is bigger than a line bump #525 still carries the pre-#488 manage_lakebase_database / manage_lakebase_branch action tables which were removed in the restructure. Could you rebase on main and redo the SKILL.md edits (trigger description append + Reference Files entry + Current Limitations pointing at references/migration.md) against the new layout? references/migration.md itself should come over cleanly. |
2 participants
Summary
Per Quentin's review on #513: rather than ship a standalone
databricks-lakebase-migrationskill, fold the content into the existingdatabricks-lakebase-autoscaleskill as a reference file. ("we already have too many skills.")This PR replaces #513.
What changed
New:
databricks-skills/databricks-lakebase-autoscale/references/migration.md(304 lines, gpt-5.5-densified from #513's 447-lineSKILL.md).Preserves the five non-obvious gotchas verbatim — these are the difference between a 30-minute migration and a 3-hour one:
CREATE DATABASEskips thedatabricks_auth+neonextensions (silent until first SP OAuth login fails)databricks_create_role(<sp-uuid>, 'SERVICE_PRINCIPAL'), not vanillaCREATE ROLEpg_restore --role=<sp-uuid>is the load-bearing flag for SP ownership of restored tablesdatabricks bundle deploycannot changedatabase.instance_nameon an existing app — workaround isdatabricks apps update --jsonwith the fullresourcesarraysync_*) do not auto-follow a re-pointed appAlso keeps: cosmetic-warning policy during
pg_restore, the common-issues table mapping every observed error string, and the Provisioned ↔ Autoscaling capacity mapping (with the unit redefinition note: Provisioned 1 CU = 16 GB; Autoscaling 1 CU = 2 GB).Updates to
SKILL.md:references/migration.mdCloses
Closes #513.
Test plan
references/migration.mdend-to-end against the originaldatabricks-lakebase-migration/SKILL.mdto confirm all five gotchas survived with full SQL/CLI fix specificsThis pull request and its description were written by Isaac.