Phase 3: Deprecate built-in PostgreSQL driver (deferred decision)

Goal

Remove the built-in PostgreSQL driver from Tabularis core, making the standalone tabularis-postgresql-plugin the sole PostgreSQL driver. This is a strategic decision that requires full team consensus and community readiness — not something to act on unilaterally.

Status: Phase 1 (plugin parity) shipped via PR #577 / #614. This issue exists so Phase 3's decision points are discoverable without digging through a merged branch's planning docs.

Target date: Oct 5, aligned with @debba, for Phase A (forced migration) below — not for deleting the built-in driver outright. Phase B (actual removal) follows once Phase A's stabilization window is clean; see "When to Revisit" and "Implementation Steps." Sequencing change: Phase 2 (plugin-exclusive features, tracked at tabularis-postgresql-plugin#9) is no longer a prerequisite for either phase — it ships after the built-in driver is removed, not before.

---

When to Revisit This Decision

This phase should be discussed when ALL of the following are true:

• Step 1 (force migration) has shipped — every saved connection still on "postgres" is automatically flipped to "postgresql" at launch (not a dismissible nudge; reuses migrateConnection's disconnect → flip → test → reopen path). The built-in driver stays in the codebase as a live fallback (undoMigration still works) during this window — see Implementation Steps below.
• The 2-week "no user-reported critical bugs" clock is measured from Step 1's release, not from a plugin RC — a voluntary-migration population is self-selected and understates real-world risk; forcing migration first is what gives an unbiased, full-population signal before the fallback is deleted for real
• No user-reported critical bugs in that 2-week window (bugs found and fixed internally during active stabilization don't reset the clock; a confirmed defect reported by a real user does)
• Plugin test suite has 100% parity with built-in (Phase 1 — done)
• Community feedback is positive (no "I want the old driver back" sentiment) — read together with the bug-report criterion above, since both are signals from the same real-world usage window

---

Decision Points

The team must agree on:

1. Plugin ID Strategy — already decided, already shipped

MIGRATABLE_DRIVERS = [("postgres", "postgresql")] (force_install.rs) plus useBuiltinPostgresMigration() are Option 2 below, already in code. No further team decision needed here — this section is kept for history/discoverability, not as an open question.

Option	Effort	User Impact
Rename plugin to "postgres" (remove guard)	Low — one code change	Zero — saved connections work unchanged
Keep "postgresql", add migration UI (chosen, shipped)	Medium — migration dialog + saved connection rewrite	Low — one-time dialog on update
Keep both (built-in frozen, plugin recommended)	Zero	Confusing — two PG drivers visible

2. Bundling Strategy

Option	Pros	Cons
Bundle plugin in app distribution	No install step, guaranteed availability	Larger app binary
Auto-install from registry on first launch	Smaller app, always latest version	Requires internet, extra startup time
Manual install (user must add via Settings)	Simplest for us	Worst UX, many users won't discover it

3. Built-in Driver Removal Scope

What gets removed from src-tauri/:

• drivers/postgres/ (2420+ lines — mod.rs, binding.rs, client.rs, explain.rs, helpers.rs, types.rs, extract/)
• PostgreSQL pool creation in pool_manager.rs
• "postgres" entry in BUILTIN_DRIVER_IDS
• PostgreSQL-specific code in commands.rs (SSH expansion for PG, postgres_dbname helper)

What stays:

• The DatabaseDriver trait (used by all drivers)
• RPC infrastructure (used by all plugins)
• Frontend driver capability handling (generic, works with any driver)

Also part of this removal scope (not just src-tauri/src/drivers/postgres/): the entire src-tauri/tests/postgres_integration/ suite (baseline, golden, and parity tests) and the .github/workflows/pg-integration.yml CI job exist solely to protect the built-in driver's behavior and to prove the plugin matches it byte-for-byte. Once the built-in driver is gone, there's nothing left for these tests to guard — they should be deleted in this same phase, not carried forward as dead weight. The plugin's own repo has its own independent test suite that continues to protect it going forward.

4. Rollback Plan

During Phase A (forced migration, built-in still in code): trivially reversible — undoMigration flips any individual connection straight back, and the built-in driver never stopped existing. This is the whole point of splitting the phases.

After Phase B (built-in actually removed) — if something goes wrong:

• Short-term: Users can install the last Tabularis version with built-in PG
• Medium-term: We can re-add the built-in driver in a patch release (code is in git history)
• Plugin-side: If the plugin has a bug, push a new plugin version (no app update needed)

---

Implementation Steps (When Decided)

Phase A — force migration (built-in stays, fully reversible):

1. Change migrateConnection from a user-clicked action into something that runs automatically for every connection in builtinConnections at launch/connection-load — same disconnect → flip driver → test → reopen → record path already in useBuiltinDriverMigration, just no longer gated on a click. Keep undoMigration and the built-in driver fully intact; this is the safety net for this whole phase.
2. Drop the dismissible nudge banner (nothing left to opt into) — replace with a one-time "we moved your PostgreSQL connections to the plugin" notice, with Undo, so the rewrite isn't silent.
3. Ship this as a normal release. Start the "When to Revisit" 2-week clock from this release, not from a plugin RC — this is the first point where the plugin carries 100% of real PostgreSQL traffic instead of a self-selected subset.
4. Watch for user-reported critical bugs and undoMigration usage during that window. Either resets the clock.

Phase B — remove the built-in (only after Phase A's window is clean — this is the actual point of no return):

5. Remove "postgres" from BUILTIN_DRIVER_IDS array
6. Remove src-tauri/src/drivers/postgres/ directory
7. Remove PG pool logic from pool_manager.rs
8. Remove postgres_dbname() helper from commands.rs
9. Remove the now-dead undoMigration/built-in fallback path from useBuiltinDriverMigration (undo has nothing to flip back to once the built-in driver is gone)
10. Update frontend: remove PG-specific fallback capabilities in useDrivers.ts
11. Update documentation: migration guide for users
12. Update CHANGELOG: announce the change prominently
13. Test: full regression suite against plugin-only configuration
14. Delete src-tauri/tests/postgres_integration/ and .github/workflows/pg-integration.yml — their only purpose was protecting/validating the built-in driver being removed in this same phase

---

Checkpoint: CP-6

When: Team decides to proceed with deprecation.

Stakeholders: Full team consensus required — not a solo decision.

Criteria for proceeding:

• All items in "When to Revisit" section are satisfied
• Team has unanimously agreed on plugin ID strategy
• Team has agreed on bundling strategy
• Rollback plan is documented and tested
• Migration path verified with test accounts (saved connections survive)
• Community announcement drafted

---

Security Consideration

Removing the built-in driver means all PostgreSQL connections flow through the plugin process (a separate child process communicating via stdio). This changes the security boundary:

Concern	Built-in	Plugin
Credential handling	In-process, same memory space	Sent via JSON over stdio (local pipes)
Connection lifetime	Managed by Tabularis process	Managed by plugin process (kill_on_drop)
Crash isolation	PG driver crash = Tabularis crash	PG driver crash = error message (Tabularis survives)
Code audit surface	Part of main codebase	Separate binary (must be audited separately)

The security posture is slightly better with the plugin (crash isolation) but introduces a new trust boundary (the plugin binary must be verified as legitimate at install time — already handled by registry SHA-256 verification).

---

Timeline Estimate

This phase is purely a coordination and removal exercise. Technical effort is minimal (< 1 week). The real timeline is governed by:

• Community confidence building (2+ weeks of stable plugin usage, no user-reported critical bugs)
• Team scheduling for the migration release
• Documentation and announcement preparation

---

Definition of Done

• Built-in PG driver code removed from Tabularis core
• Plugin is the sole PG driver, working identically
• Existing saved connections work without user action (or clear migration dialog)
• No user-facing regressions reported within 2 weeks of release
• CHANGELOG + migration guide published
• CP-6 sync completed with full team
• postgres_integration test suite and pg-integration.yml workflow removed

---

Source: .github/planning/postgres-plugin/04-phase-3-deprecate-builtin.md (in PR #577).