feat: add enable_extension tool

Phase 8, Task 8.3: mcpg/extensions.py — enable_extension runs CREATE
EXTENSION IF NOT EXISTS for names on a curated allowlist. Since an
extension name is a SQL identifier and cannot be parameterised, the
allowlist is the injection guard; unknown names are rejected before any
SQL is built. Exposed as a DDL-gated MCP tool (unrestricted + MCPG_ALLOW_DDL).
265 tests, 100% coverage of authored code.

https://claude.ai/code/session_0122yLZLJ8t4W43sdN6BmTZc

Author: claude

CHANGELOG.md

@@ -10,6 +10,8 @@ adheres to [Semantic Versioning](https://semver.org/).
 
 - `list_available_extensions` tool — lists every extension available to the
   database with its installed-vs-available status.
+- `enable_extension` tool — enables an allowlisted PostgreSQL extension;
+  requires unrestricted mode and `MCPG_ALLOW_DDL`.
 
 ### Changed
 

docs/PROGRESS.md

@@ -12,9 +12,9 @@
 
 ## Next action
 
-> Phase 8, Task 8.3 — TDD an `enable_extension` tool: `CREATE EXTENSION` gated
-> to unrestricted mode + `MCPG_ALLOW_DDL`, restricted to a known-extension
-> allowlist; extension name validated (no SQL injection).
+> Phase 8, Task 8.4 — TDD index-type-aware `recommend_indexes`: suggest GIN
+> for `jsonb`/array columns and trigram GIN for text columns frequently
+> filtered by `LIKE` (using `describe_table` column types).
 
 ## Phase 0 — Spike & foundation  ✅ COMPLETE
 
@@ -112,7 +112,7 @@
 
 - [x] 8.1 `list_indexes` reports the index access method (btree/gin/gist/...)
 - [x] 8.2 `list_available_extensions` tool — installed vs available
-- [ ] 8.3 `enable_extension` tool — gated DDL, known-extension allowlist
+- [x] 8.3 `enable_extension` tool — gated DDL, known-extension allowlist
 - [ ] 8.4 Index-type-aware `recommend_indexes` — GIN for `jsonb`/arrays,
       trigram GIN for `LIKE`, BRIN for append-only (HNSW/IVFFlat in Phase 10)
 
@@ -275,3 +275,7 @@
 - 2026-05-21 — Task 8.2: added `list_available_extensions` (`pg_available_extensions`)
   reporting every available extension with installed-vs-not status, exposed
   as an MCP tool. 258 tests, 100% coverage.
+- 2026-05-21 — Task 8.3: added `mcpg/extensions.py` — `enable_extension`
+  runs `CREATE EXTENSION IF NOT EXISTS` for names on a curated allowlist
+  (the injection guard, since the name is an identifier). Exposed as a
+  DDL-gated MCP tool. 265 tests, 100% coverage.

docs/tools.md

@@ -78,6 +78,12 @@ Executes a single DDL statement (`CREATE`/`ALTER`/`DROP` and related).
 Requires `unrestricted` mode **and** `MCPG_ALLOW_DDL=true`. Parameter: `sql`
 (string).
 
+### `enable_extension`
+Enables a known PostgreSQL extension (`CREATE EXTENSION IF NOT EXISTS`). Only
+allowlisted extensions (`pg_trgm`, `vector`, `citext`, `postgis`, ...) may be
+enabled. Requires `unrestricted` mode **and** `MCPG_ALLOW_DDL=true`.
+Parameter: `name` (string).
+
 ## Errors
 
 Tools reject unsafe or invalid input before it reaches the database. Rejected

src/mcpg/extensions.py

@@ -0,0 +1,70 @@
+"""PostgreSQL extension management.
+
+``enable_extension`` runs ``CREATE EXTENSION``. Because an extension name is
+a SQL identifier (not a bindable value), it cannot be parameterised — so only
+names on a curated allowlist may be enabled. That allowlist is the injection
+guard.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from mcpg._vendor.sql import SqlDriver
+
+# Extensions MCPg will enable on request: well-known, widely-used extensions.
+# CREATE EXTENSION takes an identifier, so this allowlist guards against
+# injection — names outside it are rejected before any SQL is built.
+ENABLEABLE_EXTENSIONS = frozenset(
+    {
+        "pg_trgm",
+        "vector",
+        "unaccent",
+        "fuzzystrmatch",
+        "citext",
+        "hstore",
+        "pgcrypto",
+        "uuid-ossp",
+        "ltree",
+        "btree_gin",
+        "btree_gist",
+        "pg_stat_statements",
+        "pgstattuple",
+        "tablefunc",
+        "intarray",
+        "cube",
+        "earthdistance",
+        "postgis",
+    }
+)
+
+
+class ExtensionError(Exception):
+    """Raised when an extension cannot be enabled."""
+
+
+@dataclass(frozen=True, slots=True)
+class EnableExtensionResult:
+    """The outcome of an enable_extension call."""
+
+    name: str
+    enabled: bool
+
+
+async def enable_extension(driver: SqlDriver, name: str) -> EnableExtensionResult:
+    """Enable a known PostgreSQL extension (``CREATE EXTENSION IF NOT EXISTS``).
+
+    Only extensions on :data:`ENABLEABLE_EXTENSIONS` may be enabled. The call
+    is idempotent.
+
+    Raises:
+        ExtensionError: If the extension is not on the allowlist, or creation
+            fails (e.g. the extension's files are not present on the server).
+    """
+    if name not in ENABLEABLE_EXTENSIONS:
+        raise ExtensionError(f"extension {name!r} is not on the allowlist of enableable extensions")
+    try:
+        await driver.execute_query(f'CREATE EXTENSION IF NOT EXISTS "{name}"', force_readonly=False)
+    except Exception as exc:
+        raise ExtensionError(str(exc)) from exc
+    return EnableExtensionResult(name=name, enabled=True)

src/mcpg/tools.py

@@ -13,7 +13,7 @@
 from mcp.server.fastmcp import Context, FastMCP
 from mcp.server.session import ServerSession
 
-from mcpg import __version__, health, indexing, introspection, query, workload, write
+from mcpg import __version__, extensions, health, indexing, introspection, query, workload, write
 from mcpg._vendor.sql import SqlDriver
 from mcpg.config import Settings
 from mcpg.context import AppContext
@@ -191,6 +191,18 @@ async def run_ddl(ctx: _Ctx, sql: str) -> dict[str, Any]:
         result = await write.run_ddl(_driver(ctx), sql)
         return asdict(result)
 
+    @server.tool(
+        name="enable_extension",
+        description=(
+            "Enable a known PostgreSQL extension (CREATE EXTENSION IF NOT "
+            "EXISTS). Only allowlisted extensions may be enabled. Available "
+            "only in unrestricted access mode with MCPG_ALLOW_DDL enabled."
+        ),
+    )
+    async def enable_extension(ctx: _Ctx, name: str) -> dict[str, Any]:
+        result = await extensions.enable_extension(_driver(ctx), name)
+        return asdict(result)
+
 
 def register_tools(server: FastMCP[AppContext], settings: Settings) -> None:
     """Register the MCP tools permitted by the configured access mode.

tests/integration/test_extensions_integration.py

@@ -0,0 +1,24 @@
+"""Integration tests for extension management against a live PostgreSQL."""
+
+import pytest
+
+from mcpg.database import Database
+from mcpg.extensions import ExtensionError, enable_extension
+from mcpg.introspection import list_available_extensions, list_extensions
+
+
+async def test_enable_extension_installs_pg_trgm(connected_database: Database) -> None:
+    driver = connected_database.driver()
+    available = {extension.name for extension in await list_available_extensions(driver)}
+    if "pg_trgm" not in available:
+        pytest.skip("pg_trgm is not available on this PostgreSQL server")
+
+    await enable_extension(driver, "pg_trgm")
+
+    installed = {extension.name for extension in await list_extensions(driver)}
+    assert "pg_trgm" in installed
+
+
+async def test_enable_extension_rejects_an_unknown_extension(connected_database: Database) -> None:
+    with pytest.raises(ExtensionError, match="allowlist"):
+        await enable_extension(connected_database.driver(), "definitely_not_a_real_extension")

tests/unit/test_extensions.py

@@ -0,0 +1,61 @@
+"""Tests for extension management and the enable_extension tool."""
+
+import pytest
+from _fakes import FakeDatabase, FakeDriver
+from mcp.shared.memory import create_connected_server_and_client_session
+
+from mcpg.config import load_settings
+from mcpg.extensions import EnableExtensionResult, ExtensionError, enable_extension
+from mcpg.server import create_server
+
+_UNRESTRICTED_DDL = load_settings(
+    {
+        "MCPG_DATABASE_URL": "postgresql://u:p@localhost/db",
+        "MCPG_ACCESS_MODE": "unrestricted",
+        "MCPG_ALLOW_DDL": "true",
+    }
+)
+_READ_ONLY = load_settings({"MCPG_DATABASE_URL": "postgresql://u:p@localhost/db"})
+
+
+async def test_enable_extension_runs_create_extension_for_an_allowlisted_name() -> None:
+    driver = FakeDriver()
+
+    result = await enable_extension(driver, "pg_trgm")
+
+    assert result == EnableExtensionResult(name="pg_trgm", enabled=True)
+    query, _params, force_readonly = driver.calls[0]
+    assert query == 'CREATE EXTENSION IF NOT EXISTS "pg_trgm"'
+    assert force_readonly is False
+
+
+async def test_enable_extension_rejects_a_name_not_on_the_allowlist() -> None:
+    driver = FakeDriver()
+
+    with pytest.raises(ExtensionError, match="allowlist"):
+        await enable_extension(driver, "evil; DROP DATABASE postgres")
+    # Rejection happens before any SQL is built.
+    assert driver.calls == []
+
+
+async def test_enable_extension_wraps_execution_failures() -> None:
+    with pytest.raises(ExtensionError, match="execution failed"):
+        await enable_extension(FakeDriver(fail=True), "pg_trgm")
+
+
+async def test_enable_extension_tool_is_callable_when_ddl_is_allowed() -> None:
+    server = create_server(_UNRESTRICTED_DDL, database=FakeDatabase(FakeDriver()))  # type: ignore[arg-type]
+
+    async with create_connected_server_and_client_session(server) as client:
+        result = await client.call_tool("enable_extension", {"name": "pg_trgm"})
+
+    assert result.isError is False
+
+
+async def test_enable_extension_tool_is_absent_without_ddl_opt_in() -> None:
+    server = create_server(_READ_ONLY, database=FakeDatabase(FakeDriver()))  # type: ignore[arg-type]
+
+    async with create_connected_server_and_client_session(server) as client:
+        names = {tool.name for tool in (await client.list_tools()).tools}
+
+    assert "enable_extension" not in names