From 19e54b10d4d955e22346339a38f34190e3a1b36b Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 4 Jul 2026 13:43:44 +0000
Subject: [PATCH] Convert /-/databases.json from top-level array to object

/-/databases.json now returns {"ok": true, "databases": [...]} instead
of a bare JSON array, so the response can grow additional keys without
a breaking change.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GrHZSypDfMnym1tM5XJAFZ
---
 datasette/app.py                  |  6 +++++-
 docs/introspection.rst            | 23 +++++++++++++----------
 existing-api.md                   |  7 ++++---
 tests/test_api.py                 |  6 ++++--
 tests/test_cli.py                 |  6 +++---
 tests/test_config_dir.py          |  2 +-
 tests/test_internals_datasette.py |  2 +-
 tests/test_routes.py              |  2 +-
 tests/test_success_envelope.py    | 11 +++++++++++
 9 files changed, 43 insertions(+), 22 deletions(-)

diff --git a/datasette/app.py b/datasette/app.py
index b554f9bc..bc35669f 100644
--- a/datasette/app.py
+++ b/datasette/app.py
@@ -2571,7 +2571,11 @@ class Datasette:
             r"/-/threads(\.(?P<format>json))?$",
         )
         add_route(
-            JsonDataView.as_view(self, "databases.json", self._connected_databases),
+            JsonDataView.as_view(
+                self,
+                "databases.json",
+                lambda: {"databases": self._connected_databases()},
+            ),
             r"/-/databases(\.(?P<format>json))?$",
         )
         add_route(
diff --git a/docs/introspection.rst b/docs/introspection.rst
index 99238204..ab47c0a5 100644
--- a/docs/introspection.rst
+++ b/docs/introspection.rst
@@ -141,16 +141,19 @@ Shows currently attached databases. `Databases example <https://latest.datasette
 
 .. code-block:: json
 
-    [
-        {
-            "hash": null,
-            "is_memory": false,
-            "is_mutable": true,
-            "name": "fixtures",
-            "path": "fixtures.db",
-            "size": 225280
-        }
-    ]
+    {
+        "ok": true,
+        "databases": [
+            {
+                "hash": null,
+                "is_memory": false,
+                "is_mutable": true,
+                "name": "fixtures",
+                "path": "fixtures.db",
+                "size": 225280
+            }
+        ]
+    }
 
 .. _JumpView:
 
diff --git a/existing-api.md b/existing-api.md
index db613d30..3348433f 100644
--- a/existing-api.md
+++ b/existing-api.md
@@ -260,9 +260,10 @@ Response: `num_threads`, `threads` (list of `{name, ident, daemon}`),
 app.py:2570-2573, `Datasette._connected_databases` (app.py:2157-2169).
 Permission `view-instance`. No parameters.
 
-Response: a JSON array of `{"name", "route", "path", "size", "is_mutable",
-"is_memory", "hash"}` — **all attached databases are listed regardless of
-per-database `view-database` permissions**.
+Response: `{"ok": true, "databases": [...]}` — each database is
+`{"name", "route", "path", "size", "is_mutable", "is_memory", "hash"}`.
+**All attached databases are listed regardless of per-database
+`view-database` permissions**.
 
 ### GET /-/actor(.json)
 
diff --git a/tests/test_api.py b/tests/test_api.py
index 3583503c..3263a88c 100644
--- a/tests/test_api.py
+++ b/tests/test_api.py
@@ -509,7 +509,7 @@ async def test_row_extra_render_cell():
 
 def test_databases_json(app_client_two_attached_databases_one_immutable):
     response = app_client_two_attached_databases_one_immutable.get("/-/databases.json")
-    databases = response.json
+    databases = response.json["databases"]
     assert 2 == len(databases)
     extra_database, fixtures_database = databases
     assert "extra database" == extra_database["name"]
@@ -775,7 +775,9 @@ def test_common_prefix_database_names(app_client_conflicting_database_names):
     # https://github.com/simonw/datasette/issues/597
     assert ["foo-bar", "foo", "fixtures"] == [
         d["name"]
-        for d in app_client_conflicting_database_names.get("/-/databases.json").json
+        for d in app_client_conflicting_database_names.get("/-/databases.json").json[
+            "databases"
+        ]
     ]
     for db_name, path in (("foo", "/foo.json"), ("foo-bar", "/foo-bar.json")):
         data = app_client_conflicting_database_names.get(path).json
diff --git a/tests/test_cli.py b/tests/test_cli.py
index f86d6909..7b528a8e 100644
--- a/tests/test_cli.py
+++ b/tests/test_cli.py
@@ -444,7 +444,7 @@ def test_serve_create(tmpdir):
         cli, [str(db_path), "--create", "--get", "/-/databases.json"]
     )
     assert result.exit_code == 0, result.output
-    databases = json.loads(result.output)
+    databases = json.loads(result.output)["databases"]
     assert {
         "name": "does_not_exist_yet",
         "is_mutable": True,
@@ -493,7 +493,7 @@ def test_serve_duplicate_database_names(tmpdir):
         conn.close()
     result = runner.invoke(cli, [db_1_path, db_2_path, "--get", "/-/databases.json"])
     assert result.exit_code == 0, result.output
-    databases = json.loads(result.output)
+    databases = json.loads(result.output)["databases"]
     assert {db["name"] for db in databases} == {"db", "db_2"}
 
 
@@ -585,7 +585,7 @@ def test_duplicate_database_files_error(tmpdir):
         cli, ["serve", other_db_path, str(config_dir), "--get", "/-/databases.json"]
     )
     assert result4.exit_code == 0
-    databases = json.loads(result4.output)
+    databases = json.loads(result4.output)["databases"]
     assert {db["name"] for db in databases} == {"other", "data"}
 
     # Test that multiple directories raise an error
diff --git a/tests/test_config_dir.py b/tests/test_config_dir.py
index 74407e20..42c6ae60 100644
--- a/tests/test_config_dir.py
+++ b/tests/test_config_dir.py
@@ -137,7 +137,7 @@ def test_static_directory_browsing_not_allowed(config_dir_client):
 def test_databases(config_dir_client):
     response = config_dir_client.get("/-/databases.json")
     assert 200 == response.status
-    databases = response.json
+    databases = response.json["databases"]
     assert 4 == len(databases)
     databases.sort(key=lambda d: d["name"])
     for db, expected_name in zip(databases, ("demo", "immutable", "j", "k")):
diff --git a/tests/test_internals_datasette.py b/tests/test_internals_datasette.py
index 1de394a5..2af069c9 100644
--- a/tests/test_internals_datasette.py
+++ b/tests/test_internals_datasette.py
@@ -167,7 +167,7 @@ def test_static_rejects_path_traversal(tmp_path, monkeypatch):
 @pytest.mark.asyncio
 async def test_datasette_constructor():
     ds = Datasette()
-    databases = (await ds.client.get("/-/databases.json")).json()
+    databases = (await ds.client.get("/-/databases.json")).json()["databases"]
     assert databases == [
         {
             "name": "_memory",
diff --git a/tests/test_routes.py b/tests/test_routes.py
index 24c702fc..4965ce76 100644
--- a/tests/test_routes.py
+++ b/tests/test_routes.py
@@ -73,7 +73,7 @@ async def ds_with_route():
 @pytest.mark.asyncio
 async def test_db_with_route_databases(ds_with_route):
     response = await ds_with_route.client.get("/-/databases.json")
-    assert response.json()[0] == {
+    assert response.json()["databases"][0] == {
         "name": "original-name",
         "route": "custom-route-name",
         "path": None,
diff --git a/tests/test_success_envelope.py b/tests/test_success_envelope.py
index cecc8d70..290a51e0 100644
--- a/tests/test_success_envelope.py
+++ b/tests/test_success_envelope.py
@@ -90,3 +90,14 @@ async def test_plugins_json_is_object(ds_client):
     response_all = await ds_client.get("/-/plugins.json?all=1")
     all_plugins = response_all.json()["plugins"]
     assert len(all_plugins) > len(data["plugins"])
+
+
+@pytest.mark.asyncio
+async def test_databases_json_is_object(ds_client):
+    response = await ds_client.get("/-/databases.json")
+    assert response.status_code == 200
+    data = response.json()
+    assert set(data.keys()) == {"ok", "databases"}
+    assert data["ok"] is True
+    assert isinstance(data["databases"], list)
+    assert "fixtures" in {db["name"] for db in data["databases"]}