Lazy-load non-essential blueprints to improve desktop startup

[dev-hari-prasad]

Problem

Some blueprints are imported during create_app() even though they are not required for desktop startup (SERVER_MODE=False). If we only import essential blueprints on startup and lazy load the other this would definetly result in faster load times.

After tracing the startup flow here is a breakdown of the blureprints and how we should ideally load them:

Modules that should remain eagerly loaded

Module	Reason
misc	Provides the /misc/ping endpoint that Electron polls while waiting for the backend to start. Without it, the application never gets past the splash screen.
browser	Hasindex(), the first page Electron loads after startup. Deferring it only shifts the wait from the splash screen to a blank window. preferences also depends on it.
Core authenticate	Required for session and login handling, even in desktop mode.

Good lazy-loading candidates

Module	Load when	Reason	Approx. size
authenticate (kerberos, ldap, mfa, oauth2, webserver)	Never in desktop mode	Gate imports in authenticate/registry.py behind config.SERVER_MODE. Desktop runs with SERVER_MODE=False and doesn't use these providers.	~14 files
tools	First tool opens	Query Tool, Debugger, Backup/Restore, ERD, Import/Export, etc. aren't needed during startup.	~155 files
llm	AI assistant opened	Depends on pgadmin.tools.user_management, so it would likely move together with tools.	~32 files
dashboard	First server/database opened	The dashboard isn't shown until after a connection is opened.	~7 files

Note: Considering how often tools are used, we can keep the tools blueprint in the early-loading category for a few select tools.

Not worth lazy-loading

These modules are tiny (1–4 files each):

• preferences
• settings
• about
• help
• redirects

Estimated impact

Potentially removes eager imports for roughly:

• tools
• llm
• External authentication backends

≈ 190 of ~915 Python files

File count is only a rough proxy and not an estimate of startup improvement.

Validation

Profile import costs:

python -X importtime -c "from pgadmin.tools import blueprint"
python -X importtime -c "from pgadmin.llm import blueprint"
python -X importtime -c "from pgadmin.authenticate.registry import AuthSourceRegistry"

Then compare against overall create_app() startup time.

Proposal

• Gate external auth provider imports behind config.SERVER_MODE.
• Lazy-load tools on first use.
• Lazy-load llm together with tools.
• Optionally lazy-load dashboard if it can be done cleanly.

I would be happy to start from the authenticate change since it's small and self-contained.

This is not a concrete implementation proposal, but rather a summary of observations from tracing the desktop startup flow and a few areas that might be worth exploring. I have not profiled import times yet but plan to do so shortly, so these suggestions are based on the current startup path and module dependencies rather than measured performance. However, I will shortly run the performance tests and provide details as a follow-up to this issue.

I would also appreciate some guidance on whether these are the right areas to target, or if there is a better approach I'm overlooking.

Thanks

[dpage]

Thanks for putting this together, it's a thoughtful write-up and the instinct to trim desktop startup is a good one. Having dug through the current code, though, I think we need to split the proposal into the part that works and the part that unfortunately can't, at least not as described.

The auth-provider bucket is the good bit. The external auth sources are only ever relevant in SERVER_MODE, and in desktop mode they expose no menu and no user-reachable route, so nothing depends on them being loaded. Gating those behind the SERVER_MODE flag is self-contained and safe, and it's the right place to start, exactly as you suggested.

The tools/llm/dashboard lazy-loading, however, runs into a chicken-and-egg problem that's baked into how the menu and routing work. When the app starts, we import each submodule and register its blueprint, and two things are then generated from the set of registered submodules: the menu bar and the endpoint table. The menu_items property walks the registered submodules and folds their menu entries together, and that's rendered straight into /browser/js/utils.js (via add_menus(...)), which the frontend loads once on the initial page. The same happens for exposed_endpoint_url_map, which becomes endpoints.js and is the table the JS uses to build tool URLs.

The consequence is that a module which isn't registered contributes no menu item and no route, so "load the tool on first use" is self-defeating: the menu entry that would trigger that first use is generated from the very module we're trying not to load. No entry, no click, no trigger.

There's also a harder constraint underneath that. We're on Flask 3.1 now, and registering a blueprint after the app has served its first request raises outright:

AssertionError: The setup method 'register_blueprint' can no longer be called
on the application. It has already handled its first request...

So on-demand registration isn't a design choice we've declined, it's something the framework actively forbids; faking it would mean a manual dispatcher or an app rebuild, which is a lot of fragile machinery. And the cost we're actually chasing is the import itself: to get the blueprint object at all we have to import the module, so we can't have the menu and routes cheaply registered whilst skipping the expensive import; one implies the other.

Where I think the real lever is for tools/llm/dashboard is not lazy-loading the blueprints, but deferring the heavy imports inside the view code (the boto3/azure/pandas-type payloads in modules like cloud), whilst keeping the lightweight blueprint, its menu, and its routes registered at startup as now. That preserves the menu and endpoint contract the frontend relies on and still trims import time, though it's a per-module refactor rather than a blanket architecture change. Profiling first would tell us which modules actually justify the effort.

[dev-hari-prasad]

Thanks for the explanation and for pointing me in the right direction. I did some digging, and I overlooked Flask's blueprint registration mechanism. Having said that, the previous proposal can't really work in the way I had originally suggested, which you already highlighted.

I will first start by working on the SERVER_MODE gating for the external authentication providers.

That said, I think there may still be another direction worth exploring.

A better workaround, in my opinion, would be to dynamically import heavy modules after profiling them based on two factors: usage and load time. If a module is used very frequently, we can avoid dynamically importing it to prevent any impact on the first-use experience. On the other hand, if a module has a significant import cost and is only used occasionally, it could be a good candidate for dynamic imports.

I don't think every module should be included in such a system. It should be limited to genuinely heavy imports where deferring the import gives a measurable startup benefit without affecting reliability or maintainability.

We could also introduce this incrementally, starting with the modules that are clearly the heaviest. Once we've measured the impact and are confident with the approach, we can always expand it to other suitable modules in future releases if it continues to make sense.

Furthermore, I will also look into profiling the modules and put together a detailed breakdown of which ones could realistically be candidates for dynamic imports. Of course, that would depend on whether you think it's a direction worth exploring and considering.

Assuming you think this is a sensible direction, I will wait for your confirmation and then follow up with a detailed profiling breakdown of the remaining modules and the best candidates for dynamic imports.