umbraco-cloud-fetch-database

Wizard-based CLI for downloading a database from Umbraco Cloud and replacing the LocalDB .mdf / .ldf files of an existing local Umbraco ASP.NET Core project.

Windows-only. LocalDB is a Windows feature; the tool refuses to run elsewhere.

What it does

Run from inside your Umbraco web project (the folder that contains *.csproj):

npx umbraco-cloud-fetch-database@latest

The wizard:

1. Verifies you are inside an Umbraco web project.
2. Lets you pick an appsettings.*.json (default appsettings.Development.json).
3. Detects how LocalDB is configured:
   • via ConnectionStrings:umbracoDbDSN containing (LocalDB) and AttachDbFileName=..., or
   • via Umbraco:Deploy:Settings:PreferLocalDbConnectionString = true (expects umbraco/Data/Umbraco.mdf).
4. Verifies the existing .mdf / .ldf files exist and are not locked.
5. Prompts for server / login / password / database of the source (cloud) database.
6. Shows a summary and asks for confirmation.
7. Ensures sqlpackage is available (auto-downloads to %USERPROFILE%\.umbraco-cloud-fetch-database\bin\sqlpackage\ if not in PATH).
8. Backs up the existing files to <dataDir>/backup/<timestamp>/ (keeps the 3 most recent backup folders).
9. Detaches the local database from (LocalDB)\MSSQLLocalDB.
10. Exports a .bacpac from the cloud server with sqlpackage /Action:Export.
11. Imports the bacpac into LocalDB under a temporary database name with sqlpackage /Action:Import.
12. Detaches the temporary database and moves its .mdf / .ldf to the project's expected paths.
13. Cleans up the bacpac on success.

Umbraco re-attaches the database on next start because of AttachDbFileName.

Prerequisites

• Windows with SQL Server Express LocalDB installed (sqllocaldb.exe).
• sqlcmd in PATH (ships with SQL Server tooling / LocalDB).
• Node.js 20+.
• sqlpackage is auto-downloaded if not in PATH.
• Your Umbraco project must already have a working LocalDB (the .mdf / .ldf must exist on disk). Start the project once if needed so Umbraco creates them.

What it changes

• Replaces the existing .mdf and .ldf files at the configured path.
• Creates <dataDir>/backup/<timestamp>/ with the previous files. Keeps the latest 3.
• Caches sqlpackage under %USERPROFILE%\.umbraco-cloud-fetch-database\bin\sqlpackage\.

The cloud database password is entered interactively and is never stored.

Releasing (maintainers)

CI is GitHub Actions:

• ci.yml runs build/typecheck on push and PR.
• release.yml runs on push to main. It uses npm Trusted Publishing (OIDC, no NPM_TOKEN secret) and only publishes if the version in package.json is not already on npm.

To release: bump the version in package.json in a commit, merge to main, done.

License

MIT