DataGrip Smart SQL Navigation: Architecture Note on Schema-Aware Completion and Plan Previews

Problem

Schema-aware code completion and inline execution plan previews in DataGrip are useful only when the IDE’s local view of the database matches reality. The practical risk is stale metadata leading to confident but wrong completions, or plan previews that no longer reflect the current transaction state.

The useful takeaway is to treat DataGrip’s smart navigation as a read-through cache over a live JDBC connection, not as a source of truth. Design decisions should keep the trust boundary at the connection, make cache refresh explicit, and limit scope to avoid UI lag on large schemas.

Requirements

Smart SQL navigation requires a live JDBC connection to the target data source. Completion and plan previews are generated from database schema metadata, not from static files.

• Context-aware completion for DDL and DML based on tables, columns, and types visible to the connection user.
• Inline execution plan preview that runs an EXPLAIN variant through the same connection and discards the result on rollback.
• On-demand metadata refresh with a manual override, because schema can change outside the IDE session.
• Minimal performance impact for read-only work; heavy introspection must be scoped.

Smallest suitable design

The minimal design is a per-data-source local metadata cache in the IDE, populated on first use and refreshed on demand.

Completion provider reads the cache. Plan preview executes via the active JDBC connection and is tied to the current transaction. When a transaction is rolled back, the previewed plan is discarded to avoid stale decision data.

Scope control is implemented by limiting inspected schemas and objects. In the Database tool window you can select specific schemas for inspection rather than the entire catalog. This reduces initial introspection cost and UI lag.

Example configuration check: Settings > Database > General. Verify Smart completion is enabled for the target data source. In the Database tool window, the Refresh schema action forces a fresh metadata load from the database, confirming cache behavior.

Trust and data boundaries

Trust boundary is the active JDBC connection. DataGrip does not maintain server-side state for completion. All metadata is cached locally and is only as fresh as the last refresh.

The IDE has no visibility into changes made by other sessions after the cache was built. Dynamic objects created after the session starts may be missing from suggestions until a refresh.

Plan previews require sufficient privileges to run EXPLAIN. A read-only user can complete queries but cannot fetch execution plans or modify DDL, limiting usefulness.

Operational checks

Practical checks to confirm the feature is operating as designed.

• Open Settings > Database > General and confirm Smart completion is enabled for the data source.
• Create a simple SELECT and observe column names and table aliases appear as you type. This confirms the completion provider is reading the cache.
• Use the Refresh schema button in the Database tool window to force a metadata reload and verify the cache updates.

Limit the inspected schema scope for large catalogs to keep introspection fast. Monitor UI responsiveness during initial schema load.

Failure modes

Incorrect schema caching can lead to outdated column types. The IDE will suggest a column that has changed type, causing runtime errors not flagged by the IDE.

Driver version changes can degrade suggestion accuracy. A DataGrip restart or manual cache clear is needed to re-synchronize when the underlying DB driver changes.

Network interruption during metadata refresh can corrupt the local cache. Manual cache invalidation and re-refresh is required.

Heavy introspection on large schemas can cause UI lag. Mitigation is schema scoping and incremental refresh.

When to change the design

Consider a different approach if you need shared, authoritative metadata across a team, or if schema changes are frequent and must be reflected without manual refresh. In that case a centralized schema registry or CI-driven catalog sync would be needed.

If you require plan previews in environments where EXPLAIN is disallowed or expensive, disable inline previews and rely on explicit EXPLAIN execution in a controlled session.

If the connection is read-only by policy, expect completion only. Plan preview and DDL assistance will be limited.