docs(datatables): describe the external instance cluster and how to run one locally

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

AGENTS.md

@@ -29,6 +29,10 @@ Open-source platform for internal tools, workflows, API integrations, background
 - **Agent workers**: `docs/agent-worker-e2e.md` — building and running one locally. An agent
   reaches the DB only through the API, so `Connection::Http` paths are never taken by a plain
   `cargo run`; a normal build cannot start one at all.
+- **External instance data tables**: `docs/external-instance-datatables.md` — the cluster Windmill
+  administers behind `external_instance` data tables and Ducklake catalogs: its invariants (one
+  lifecycle lock, managed-object markers, the setup gate, per-cluster roles, fork copy ownership)
+  and how to run one locally
 - **Enterprise**: `docs/enterprise.md` — EE file conventions and PR workflow
 - **Auth surface**: `docs/auth-surface.md` — credential precedence, session/cache invalidation
   scope, which token labels email their owner at expiry, how OAuth login matches `login_type`, and

backend/.sqlx/query-06abbf945bee93349ff88f64906b96ea1e853ef202510281427cfa9beeff81b3.json

@@ -0,0 +1,22 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "SELECT 1 AS one FROM workspace_settings WHERE workspace_id = $1 FOR UPDATE",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "one",
+        "type_info": "Int4"
+      }
+    ],
+    "parameters": {
+      "Left": [
+        "Text"
+      ]
+    },
+    "nullable": [
+      null
+    ]
+  },
+  "hash": "06abbf945bee93349ff88f64906b96ea1e853ef202510281427cfa9beeff81b3"
+}

backend/.sqlx/query-06ce02cd7ce2f5a57355153edb573c242f9ba758db66e9a5e16f30e3e1494201.json

@@ -0,0 +1,16 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "UPDATE workspace_settings ws\n           SET datatable = (\n               SELECT jsonb_set(ws.datatable, '{datatables}', jsonb_object_agg(\n                   dt.key,\n                   CASE WHEN dt.value->'reference'->>'workspace_id' = $1\n                             AND dt.value->'reference'->>'datatable' = $2\n                       THEN jsonb_set(dt.value, '{reference,datatable}', to_jsonb($3::text))\n                       ELSE dt.value END\n               ))\n               FROM jsonb_each(ws.datatable->'datatables') dt\n           )\n           WHERE EXISTS (\n               SELECT 1 FROM jsonb_each(COALESCE(ws.datatable->'datatables', '{}'::jsonb)) d\n               WHERE d.value->'reference'->>'workspace_id' = $1\n                 AND d.value->'reference'->>'datatable' = $2\n           )",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Left": [
+        "Text",
+        "Text",
+        "Text"
+      ]
+    },
+    "nullable": []
+  },
+  "hash": "06ce02cd7ce2f5a57355153edb573c242f9ba758db66e9a5e16f30e3e1494201"
+}

backend/.sqlx/query-0d10e0fa5cf4033c7d93c9ed56be8209046007917f44da954eccf2188e5bff1f.json

@@ -0,0 +1,29 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "SELECT permissioned_as, permissioned_as_email FROM v2_job\n                 WHERE id = $1 AND workspace_id = $2",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "permissioned_as",
+        "type_info": "Varchar"
+      },
+      {
+        "ordinal": 1,
+        "name": "permissioned_as_email",
+        "type_info": "Varchar"
+      }
+    ],
+    "parameters": {
+      "Left": [
+        "Uuid",
+        "Text"
+      ]
+    },
+    "nullable": [
+      false,
+      false
+    ]
+  },
+  "hash": "0d10e0fa5cf4033c7d93c9ed56be8209046007917f44da954eccf2188e5bff1f"
+}

backend/.sqlx/query-297c7a40dfce729d44aa37bc7c65560517bd25e40c0752a00467829191e2eb98.json

@@ -0,0 +1,15 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "UPDATE workspace_settings ws\n           SET datatable = (\n               SELECT jsonb_set(ws.datatable, '{datatables}', jsonb_object_agg(\n                   dt.key,\n                   CASE WHEN dt.value->'reference'->>'workspace_id' = $2\n                       THEN jsonb_set(dt.value, '{reference,workspace_id}', to_jsonb($1::text))\n                       ELSE dt.value END\n               ))\n               FROM jsonb_each(ws.datatable->'datatables') dt\n           )\n           WHERE jsonb_typeof(ws.datatable->'datatables') = 'object'\n             AND ws.datatable::text LIKE '%\"reference\"%'",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Left": [
+        "Text",
+        "Text"
+      ]
+    },
+    "nullable": []
+  },
+  "hash": "297c7a40dfce729d44aa37bc7c65560517bd25e40c0752a00467829191e2eb98"
+}

backend/.sqlx/query-2a391cc1bfcd2f75b46144a394c01237e09c3060da88170f1f6e06468309d213.json

@@ -0,0 +1,16 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "UPDATE capture_config SET server_id = NULL, last_server_ping = NULL\n             WHERE workspace_id = $1 AND trigger_kind = 'postgres'\n               AND (trigger_config->>'postgres_resource_path' = $2\n                    OR trigger_config->>'postgres_resource_path' LIKE $3)",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Left": [
+        "Text",
+        "Text",
+        "Text"
+      ]
+    },
+    "nullable": []
+  },
+  "hash": "2a391cc1bfcd2f75b46144a394c01237e09c3060da88170f1f6e06468309d213"
+}

backend/.sqlx/query-334dbcd48fb59c96c62c2705ab2d1ce716cd52417f487cc1a8dd376017b2db7d.json

@@ -0,0 +1,22 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "SELECT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = $1)",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "exists",
+        "type_info": "Bool"
+      }
+    ],
+    "parameters": {
+      "Left": [
+        "Name"
+      ]
+    },
+    "nullable": [
+      null
+    ]
+  },
+  "hash": "334dbcd48fb59c96c62c2705ab2d1ce716cd52417f487cc1a8dd376017b2db7d"
+}

backend/.sqlx/query-4692810d2be817bbb5de9b476d68d695941bd4fb5ccef393e4da522ed479d601.json

@@ -0,0 +1,16 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "UPDATE postgres_trigger SET server_id = NULL, last_server_ping = NULL\n         WHERE workspace_id = $1\n           AND (postgres_resource_path = $2 OR postgres_resource_path LIKE $3)",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Left": [
+        "Text",
+        "Text",
+        "Text"
+      ]
+    },
+    "nullable": []
+  },
+  "hash": "4692810d2be817bbb5de9b476d68d695941bd4fb5ccef393e4da522ed479d601"
+}

backend/.sqlx/query-5048e21546f9710697100100e1255ab103979433bc386d7c89d0e30db12bfd57.json

@@ -0,0 +1,29 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "SELECT ws.workspace_id AS \"workspace_id!\", dt.key AS \"datatable!\"\n           FROM workspace_settings ws\n           CROSS JOIN LATERAL jsonb_each(COALESCE(ws.datatable->'datatables', '{}'::jsonb)) dt\n           WHERE dt.value->'reference'->>'workspace_id' = $1\n             AND dt.value->'reference'->>'datatable' = $2",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "workspace_id!",
+        "type_info": "Varchar"
+      },
+      {
+        "ordinal": 1,
+        "name": "datatable!",
+        "type_info": "Text"
+      }
+    ],
+    "parameters": {
+      "Left": [
+        "Text",
+        "Text"
+      ]
+    },
+    "nullable": [
+      false,
+      null
+    ]
+  },
+  "hash": "5048e21546f9710697100100e1255ab103979433bc386d7c89d0e30db12bfd57"
+}

backend/.sqlx/query-538dd1779874e4003932d7f17750239c625f85e25b3364bf2edf566f518c8ee2.json

@@ -0,0 +1,29 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "SELECT ws.workspace_id AS \"workspace_id!\", dt.key AS \"datatable!\"\n               FROM workspace_settings ws\n               CROSS JOIN LATERAL jsonb_each(COALESCE(ws.datatable->'datatables', '{}'::jsonb)) dt\n               WHERE dt.value->'reference'->>'workspace_id' = $1\n                 AND dt.value->'reference'->>'datatable' = $2",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "workspace_id!",
+        "type_info": "Varchar"
+      },
+      {
+        "ordinal": 1,
+        "name": "datatable!",
+        "type_info": "Text"
+      }
+    ],
+    "parameters": {
+      "Left": [
+        "Text",
+        "Text"
+      ]
+    },
+    "nullable": [
+      false,
+      null
+    ]
+  },
+  "hash": "538dd1779874e4003932d7f17750239c625f85e25b3364bf2edf566f518c8ee2"
+}

backend/.sqlx/query-58e5cfe9eb87bda9f7de87c403861b6e7b9d35a41594681e2a92a87359e6a018.json

@@ -0,0 +1,23 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "SELECT username FROM usr WHERE workspace_id = $1 AND email = $2 AND disabled = false",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "username",
+        "type_info": "Varchar"
+      }
+    ],
+    "parameters": {
+      "Left": [
+        "Text",
+        "Text"
+      ]
+    },
+    "nullable": [
+      false
+    ]
+  },
+  "hash": "58e5cfe9eb87bda9f7de87c403861b6e7b9d35a41594681e2a92a87359e6a018"
+}

backend/.sqlx/query-6f9fb5d72f486358fa25d6887bd69b93910e028f140c07048f2c1c8d63ee6909.json

@@ -0,0 +1,15 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "INSERT INTO global_settings (name, value) VALUES ($1, $2)\n         ON CONFLICT (name) DO UPDATE SET value = $2",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Left": [
+        "Varchar",
+        "Jsonb"
+      ]
+    },
+    "nullable": []
+  },
+  "hash": "6f9fb5d72f486358fa25d6887bd69b93910e028f140c07048f2c1c8d63ee6909"
+}

backend/.sqlx/query-975e404ac3a6258bb8220e122e3de094c7ab23330fdbc74d6e4ad472ddd3c820.json

@@ -0,0 +1,15 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "INSERT INTO global_settings (name, value) VALUES ($1, $2)\n         ON CONFLICT (name) DO UPDATE SET value = $2, updated_at = now()",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Left": [
+        "Varchar",
+        "Jsonb"
+      ]
+    },
+    "nullable": []
+  },
+  "hash": "975e404ac3a6258bb8220e122e3de094c7ab23330fdbc74d6e4ad472ddd3c820"
+}

backend/.sqlx/query-9f663180166f53d117e794f3f3a5723a0a43db163ecca7d5a63d4e74ab1d3be1.json

@@ -0,0 +1,20 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "SELECT pg_advisory_xact_lock(hashtext('datatable_role_catalog'))",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "pg_advisory_xact_lock",
+        "type_info": "Void"
+      }
+    ],
+    "parameters": {
+      "Left": []
+    },
+    "nullable": [
+      null
+    ]
+  },
+  "hash": "9f663180166f53d117e794f3f3a5723a0a43db163ecca7d5a63d4e74ab1d3be1"
+}

backend/.sqlx/query-a57de2bb0442a5ee8a607cd63cfcf675de175796184f620cb4b09670c8b0b19f.json

@@ -0,0 +1,16 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "UPDATE capture_config SET server_id = NULL, last_server_ping = NULL\n         WHERE workspace_id = $1 AND trigger_kind = 'postgres'\n           AND (trigger_config->>'postgres_resource_path' = $2\n                OR trigger_config->>'postgres_resource_path' LIKE $3)",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Left": [
+        "Text",
+        "Text",
+        "Text"
+      ]
+    },
+    "nullable": []
+  },
+  "hash": "a57de2bb0442a5ee8a607cd63cfcf675de175796184f620cb4b09670c8b0b19f"
+}

backend/.sqlx/query-b42af37fb474bea4c5419b0a46d9eadfe384013ab970ccf9c5effd1c78321b7c.json

@@ -0,0 +1,22 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "SELECT ws.datatable->'datatables' FROM workspace_settings ws\n             WHERE ws.workspace_id = $1 FOR UPDATE",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "?column?",
+        "type_info": "Jsonb"
+      }
+    ],
+    "parameters": {
+      "Left": [
+        "Text"
+      ]
+    },
+    "nullable": [
+      null
+    ]
+  },
+  "hash": "b42af37fb474bea4c5419b0a46d9eadfe384013ab970ccf9c5effd1c78321b7c"
+}

backend/.sqlx/query-c1d026c886799dabc39ce73e1fe09ccb175c7271df75d67aa9c72ad6f825a992.json

@@ -0,0 +1,28 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "DELETE FROM usr WHERE email = $1 RETURNING username, workspace_id",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "username",
+        "type_info": "Varchar"
+      },
+      {
+        "ordinal": 1,
+        "name": "workspace_id",
+        "type_info": "Varchar"
+      }
+    ],
+    "parameters": {
+      "Left": [
+        "Text"
+      ]
+    },
+    "nullable": [
+      false,
+      false
+    ]
+  },
+  "hash": "c1d026c886799dabc39ce73e1fe09ccb175c7271df75d67aa9c72ad6f825a992"
+}

backend/.sqlx/query-c5451ea9d9fa5146af242d1ee8c19ebd65b80e7ed9f29b9fb2e03767c2aa94ba.json

@@ -0,0 +1,28 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "SELECT ws.workspace_id AS \"workspace_id!\", dt.key AS \"datatable!\"\n           FROM workspace_settings ws\n           CROSS JOIN LATERAL jsonb_each(COALESCE(ws.datatable->'datatables', '{}'::jsonb)) dt\n           WHERE dt.value->'reference'->>'workspace_id' = $1\n           ORDER BY ws.workspace_id, dt.key",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "workspace_id!",
+        "type_info": "Varchar"
+      },
+      {
+        "ordinal": 1,
+        "name": "datatable!",
+        "type_info": "Text"
+      }
+    ],
+    "parameters": {
+      "Left": [
+        "Text"
+      ]
+    },
+    "nullable": [
+      false,
+      null
+    ]
+  },
+  "hash": "c5451ea9d9fa5146af242d1ee8c19ebd65b80e7ed9f29b9fb2e03767c2aa94ba"
+}

backend/.sqlx/query-c85d362fe2e652d4ac01a35bf470e80b993020a2ff5dcb5849dc570d52798587.json

@@ -0,0 +1,14 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "DELETE FROM datatable_role WHERE id = $1",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Left": [
+        "Text"
+      ]
+    },
+    "nullable": []
+  },
+  "hash": "c85d362fe2e652d4ac01a35bf470e80b993020a2ff5dcb5849dc570d52798587"
+}

backend/.sqlx/query-d5fb5dde6300862f978739a3d9249fc2b3e7697c0da7d3195398933d3d81aadf.json

@@ -0,0 +1,22 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "SELECT datatable FROM workspace_settings WHERE workspace_id = $1",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "datatable",
+        "type_info": "Jsonb"
+      }
+    ],
+    "parameters": {
+      "Left": [
+        "Text"
+      ]
+    },
+    "nullable": [
+      true
+    ]
+  },
+  "hash": "d5fb5dde6300862f978739a3d9249fc2b3e7697c0da7d3195398933d3d81aadf"
+}

backend/.sqlx/query-da5057c86607327bafc2942c218025ca9181a0c396405984d87e422e129521c1.json

@@ -0,0 +1,16 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "UPDATE workspace_settings ws\n               SET datatable = (\n                   SELECT jsonb_set(ws.datatable, '{datatables}', jsonb_object_agg(\n                       dt.key,\n                       CASE WHEN dt.value->'reference'->>'workspace_id' = $1\n                                 AND dt.value->'reference'->>'datatable' = $2\n                           THEN jsonb_set(dt.value, '{reference,datatable}', to_jsonb($3::text))\n                           ELSE dt.value END\n                   ))\n                   FROM jsonb_each(ws.datatable->'datatables') dt\n               )\n               WHERE jsonb_typeof(ws.datatable->'datatables') = 'object'\n                 AND ws.datatable::text LIKE '%\"reference\"%'",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Left": [
+        "Text",
+        "Text",
+        "Text"
+      ]
+    },
+    "nullable": []
+  },
+  "hash": "da5057c86607327bafc2942c218025ca9181a0c396405984d87e422e129521c1"
+}

backend/.sqlx/query-dc8dfc37559e9b6713bde48155f48b5a2c7b8199eace1508e102b60d1ff40c04.json

@@ -0,0 +1,20 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "SELECT value->'roles' FROM global_settings WHERE name = 'custom_instance_pg_databases'",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "?column?",
+        "type_info": "Jsonb"
+      }
+    ],
+    "parameters": {
+      "Left": []
+    },
+    "nullable": [
+      null
+    ]
+  },
+  "hash": "dc8dfc37559e9b6713bde48155f48b5a2c7b8199eace1508e102b60d1ff40c04"
+}

backend/.sqlx/query-e159b2ff15633f85e839ee4fe1ec2ecd11caf228ea8d0f52ad66def595644250.json

@@ -0,0 +1,16 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "UPDATE postgres_trigger SET server_id = NULL, last_server_ping = NULL\n             WHERE workspace_id = $1\n               AND (postgres_resource_path = $2 OR postgres_resource_path LIKE $3)",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Left": [
+        "Text",
+        "Text",
+        "Text"
+      ]
+    },
+    "nullable": []
+  },
+  "hash": "e159b2ff15633f85e839ee4fe1ec2ecd11caf228ea8d0f52ad66def595644250"
+}

backend/.sqlx/query-e2061df65ffd4a72146c4ca316829265289c8d6f625ac272655c88e1ad0b1745.json

@@ -0,0 +1,22 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "SELECT datatable FROM workspace_settings WHERE workspace_id = $1 FOR UPDATE",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "datatable",
+        "type_info": "Jsonb"
+      }
+    ],
+    "parameters": {
+      "Left": [
+        "Text"
+      ]
+    },
+    "nullable": [
+      true
+    ]
+  },
+  "hash": "e2061df65ffd4a72146c4ca316829265289c8d6f625ac272655c88e1ad0b1745"
+}

backend/.sqlx/query-ebaf3ed3097621da59dd201b5a4b9d1f440692f183c7c378f59e4b73f1c6e241.json

@@ -0,0 +1,17 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "UPDATE workspace_settings\n               SET datatable = jsonb_set(\n                   jsonb_set(\n                       datatable #- ARRAY['datatables', $2, 'reference'],\n                       ARRAY['datatables', $2, 'database'], $3::jsonb),\n                   ARRAY['datatables', $2, 'forked_from'], $4::jsonb\n               )\n               WHERE workspace_id = $1",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Left": [
+        "Text",
+        "Text",
+        "Jsonb",
+        "Jsonb"
+      ]
+    },
+    "nullable": []
+  },
+  "hash": "ebaf3ed3097621da59dd201b5a4b9d1f440692f183c7c378f59e4b73f1c6e241"
+}

backend/.sqlx/query-f3ee09fb17955ca8d886f446d397063c4094546a7807343b570b823796372cef.json

@@ -0,0 +1,22 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "SELECT workspace_id FROM workspace_settings WHERE datatable::text LIKE $1",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "workspace_id",
+        "type_info": "Varchar"
+      }
+    ],
+    "parameters": {
+      "Left": [
+        "Text"
+      ]
+    },
+    "nullable": [
+      false
+    ]
+  },
+  "hash": "f3ee09fb17955ca8d886f446d397063c4094546a7807343b570b823796372cef"
+}

backend/.sqlx/query-f4adc9e26ebfebce18a29fb2c21bf06394cacb8a9699a608327b097e0ac1363e.json

@@ -0,0 +1,16 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "UPDATE workspace_settings\n           SET datatable = CASE WHEN $3::jsonb = 'null'::jsonb\n               THEN datatable #- ARRAY['datatables', $2, 'permissions']\n               ELSE jsonb_set(datatable, ARRAY['datatables', $2, 'permissions'], $3::jsonb)\n           END\n           WHERE workspace_id = $1",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Left": [
+        "Text",
+        "Text",
+        "Jsonb"
+      ]
+    },
+    "nullable": []
+  },
+  "hash": "f4adc9e26ebfebce18a29fb2c21bf06394cacb8a9699a608327b097e0ac1363e"
+}

backend/.sqlx/query-fcb34e643b888122766e115a01394ab31ac856252aaa76c75ea27a447009c363.json

@@ -0,0 +1,17 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "UPDATE datatable_role SET name = $2, enabled = $3, pwd = $4 WHERE id = $1",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Left": [
+        "Text",
+        "Varchar",
+        "Bool",
+        "Text"
+      ]
+    },
+    "nullable": []
+  },
+  "hash": "fcb34e643b888122766e115a01394ab31ac856252aaa76c75ea27a447009c363"
+}

backend/Cargo.lock

@@ -15470,6 +15470,7 @@ dependencies = [
  "windmill-ai",
  "windmill-alerting",
  "windmill-api-auth",
+ "windmill-audit",
  "windmill-common",
  "windmill-object-store",
 ]
@@ -15652,6 +15653,7 @@ dependencies = [
  "pin-project-lite",
  "pkcs1",
  "postgres-native-tls 0.5.3",
+ "postgres-protocol",
  "prometheus",
  "quick_cache",
  "rand 0.9.0",

backend/Cargo.toml

@@ -624,6 +624,7 @@ wasm-bindgen-test = "^0"
 convert_case = "0.6.0"
 getrandom = "0.2"
 tokio-postgres = {version = "^0.7", features = ["array-impls", "with-serde_json-1", "with-chrono-0_4", "with-uuid-1", "with-bit-vec-0_6"]}
+postgres-protocol = "0.6"
 rust-postgres = { package = "tokio-postgres", git = "https://github.com/MaterializeInc/rust-postgres", rev = "78c1222577bb091d69bc22b1bc7ad01c14675abe"}
 rust-postgres-native-tls = { package = "postgres-native-tls", git = "https://github.com/MaterializeInc/rust-postgres", features = ["runtime"], rev = "78c1222577bb091d69bc22b1bc7ad01c14675abe" }
 bit-vec = "=0.6.3"

backend/ee-repo-ref.txt

@@ -1 +1 @@
-d252afcc80e77fcc4f9a2a346b80908c8605a6c0
+151be033ea2bf2f768f381a8cd3b888bdd366cf9

backend/migrations/20260908142148_datatable_role_catalog.down.sql

@@ -0,0 +1,18 @@
+-- Refuse while the catalog holds anything. Each row is a live Postgres login with a password
+-- only this table carries, so dropping it would leave credentials on the cluster that Windmill can
+-- no longer disable, delete or even name — and re-applying could not recreate them, because the
+-- role names would already be taken. Cleaning them up here is not an option either: dropping a
+-- role means reassigning what it owns in *every* instance database, and a migration runs in one.
+--
+-- Delete the roles through instance settings first; that path does the cluster work.
+LOCK TABLE datatable_role IN ACCESS EXCLUSIVE MODE;
+
+DO $$
+BEGIN
+    IF EXISTS (SELECT 1 FROM datatable_role) THEN
+        RAISE EXCEPTION 'Cannot roll back: % data table role(s) still exist as Postgres logins. Delete them in instance settings first, which drops them from the cluster.',
+            (SELECT count(*) FROM datatable_role);
+    END IF;
+END $$;
+
+DROP TABLE IF EXISTS datatable_role;

backend/migrations/20260908142148_datatable_role_catalog.up.sql

@@ -0,0 +1,21 @@
+-- The instance's data table role catalog: one row per Postgres login Windmill created for data
+-- table access.
+--
+-- A table rather than a `global_settings` key, because the value is a set of live cluster
+-- credentials and that table has generic read, list, write and CLI round-trip paths that know
+-- nothing about what they are carrying. Every one of them is a way to leak the passwords or to
+-- overwrite the catalog with a copy that has none, and a row nothing generic touches has none of
+-- those. One row per role also makes two concurrent creates two inserts rather than a
+-- read-modify-write over one document.
+CREATE TABLE datatable_role (
+    id VARCHAR(50) PRIMARY KEY,
+    -- The Postgres role name, verbatim. Unique because it is the cluster's own key.
+    name VARCHAR(63) NOT NULL UNIQUE,
+    enabled BOOLEAN NOT NULL DEFAULT true,
+    -- Generated by Windmill, never entered by anyone, and never leaves the server.
+    pwd TEXT,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+GRANT ALL ON datatable_role TO windmill_user;
+GRANT ALL ON datatable_role TO windmill_admin;

backend/migrations/20260917133824_datatable_role_cluster.down.sql

@@ -0,0 +1,22 @@
+-- Roles on the external cluster are live logins there; dropping the column would forget them.
+LOCK TABLE datatable_role;
+DO $$
+BEGIN
+    IF EXISTS (SELECT 1 FROM datatable_role WHERE cluster <> 'instance') THEN
+        RAISE EXCEPTION 'datatable_role holds roles on the external instance cluster. Delete them in instance settings first.';
+    END IF;
+    -- Before this, only data tables on Windmill's own cluster could be under roles, and a role
+    -- block left with just `admin` survives deleting every external role.
+    IF EXISTS (
+        SELECT 1 FROM workspace_settings ws,
+            jsonb_each(CASE WHEN jsonb_typeof(ws.datatable->'datatables') = 'object'
+                THEN ws.datatable->'datatables' ELSE '{}'::jsonb END) dt
+        WHERE dt.value->'database'->>'resource_type' = 'external_instance'
+          AND dt.value ? 'permissions'
+    ) THEN
+        RAISE EXCEPTION 'external instance data tables are still under roles. Turn their roles off first.';
+    END IF;
+END $$;
+ALTER TABLE datatable_role DROP CONSTRAINT datatable_role_cluster_name_key;
+ALTER TABLE datatable_role ADD CONSTRAINT datatable_role_name_key UNIQUE (name);
+ALTER TABLE datatable_role DROP COLUMN cluster;

backend/migrations/20260917133824_datatable_role_cluster.up.sql

@@ -0,0 +1,8 @@
+-- A data table role is a Postgres login on one cluster: Windmill's own ('instance'), or the external
+-- instance cluster ('external_instance'). Role names are the cluster's own key, so they are unique
+-- per cluster rather than across the instance.
+ALTER TABLE datatable_role
+    ADD COLUMN cluster VARCHAR(20) NOT NULL DEFAULT 'instance'
+        CHECK (cluster IN ('instance', 'external_instance'));
+ALTER TABLE datatable_role DROP CONSTRAINT datatable_role_name_key;
+ALTER TABLE datatable_role ADD CONSTRAINT datatable_role_cluster_name_key UNIQUE (cluster, name);

backend/parsers/windmill-parser/src/asset_parser.rs

@@ -730,7 +730,12 @@ pub fn parse_asset_syntax(
     s: &str,
     enable_default_syntax: bool,
 ) -> Option<(AssetKind, Cow<'_, str>)> {
-    if enable_default_syntax && s == "datatable" {
+    // `datatable` and `datatable?role=analyst` both name the default data table: the role picks
+    // which Postgres login the connection is made as, not which data table is read.
+    if enable_default_syntax
+        && s.strip_prefix("datatable")
+            .is_some_and(|rest| rest.is_empty() || rest.starts_with('?'))
+    {
         return Some((AssetKind::DataTable, Cow::Borrowed("main")));
     } else if enable_default_syntax && s == "ducklake" {
         return Some((AssetKind::Ducklake, Cow::Borrowed("main")));
@@ -741,6 +746,14 @@ pub fn parse_asset_syntax(
             if *kind == AssetKind::Dbt {
                 return Some((*kind, Cow::Owned(canonicalize_table_asset_path(suffix))));
             }
+            // Same reasoning as above, for the explicit form. Specific to data tables: a
+            // `Resource`'s `?table=` is part of what it names, and stripping it would merge two
+            // different assets.
+            if *kind == AssetKind::DataTable {
+                if let Some((path, _role)) = suffix.split_once('?') {
+                    return Some((*kind, Cow::Borrowed(path)));
+                }
+            }
             // The suffix is kept verbatim. For S3 the path encodes the storage:
             // `s3://<storage>/<key>`, with an EMPTY storage segment for the
             // workspace default — so `s3:///key` yields `/key` (leading slash
@@ -1692,6 +1705,25 @@ fn parse_trigger_spec(s: &str) -> Option<TriggerSpec> {
 mod pipeline_annotation_tests {
     use super::*;
 
+    #[test]
+    fn a_datatable_role_is_not_part_of_the_asset_it_names() {
+        // The role picks which Postgres login the connection is made as, so two references that
+        // differ only by role are the same asset and must land on one graph node.
+        assert_eq!(
+            parse_asset_syntax("datatable://sales?role=analytics", false),
+            Some((AssetKind::DataTable, Cow::Borrowed("sales")))
+        );
+        assert_eq!(
+            parse_asset_syntax("datatable?role=analytics", true),
+            Some((AssetKind::DataTable, Cow::Borrowed("main")))
+        );
+        // A resource's `?table=` is part of what it names, so it is kept.
+        assert_eq!(
+            parse_asset_syntax("$res:f/db/pg?table=users", false),
+            Some((AssetKind::Resource, Cow::Borrowed("f/db/pg?table=users")))
+        );
+    }
+
     #[test]
     fn s3_path_keeps_storage_distinction() {
         // An S3 asset path is `<storage>/<key>` with an empty storage segment

backend/windmill-api-groups/src/folders.rs

@@ -800,6 +800,14 @@ async fn delete_folder(
 
     not_found_if_none(get_folderopt(&mut tx, &w_id, &name).await?, "Folder", &name)?;
 
+    // See the same call in `delete_group`: a freed name must not stay in a tenant list.
+    windmill_common::workspaces::remove_datatable_tenant_in_workspace(
+        &mut tx,
+        &w_id,
+        &format!("f/{name}"),
+    )
+    .await?;
+
     let del = sqlx::query_scalar!(
         "DELETE FROM folder WHERE name = $1 AND workspace_id = $2 RETURNING 1",
         name,

backend/windmill-api-groups/src/groups.rs

@@ -797,6 +797,15 @@ async fn delete_group(
     }
     not_found_if_none(get_group_opt(&mut tx, &w_id, &name).await?, "Group", &name)?;
 
+    // A tenant list names a principal, so a freed name must not linger in one: a later group
+    // reusing it would silently inherit the data table access this one had.
+    windmill_common::workspaces::remove_datatable_tenant_in_workspace(
+        &mut tx,
+        &w_id,
+        &format!("g/{name}"),
+    )
+    .await?;
+
     sqlx::query!(
         "DELETE FROM usr_to_group WHERE group_ = $1 AND workspace_id = $2",
         name,

backend/windmill-api-integration-tests/tests/datatable_acl.rs

@@ -0,0 +1,108 @@
+//! Who may read and change a data table's grants and owners. On the Enterprise Edition: its
+//! administrators, from the workspace that governs it. Without it: nobody. Each refusal is decided
+//! before anything connects to the data table, so the fixture's database never has to exist.
+
+use serde_json::{json, Value};
+use sqlx::{Pool, Postgres};
+
+use windmill_test_utils::*;
+
+fn grant_select_on_public() -> Value {
+    json!({
+        "target": {"kind": "schema", "schema": "public"},
+        "change": {"type": "grant", "role": "analytics", "privileges": ["SELECT"],
+                   "scope": "all_tables"},
+        "statements": [r#"GRANT SELECT ON ALL TABLES IN SCHEMA "public" TO "analytics""#]
+    })
+}
+
+async fn post_acl(
+    port: u16,
+    w_id: &str,
+    action: &str,
+    token: &str,
+) -> anyhow::Result<reqwest::Response> {
+    Ok(reqwest::Client::new()
+        .post(format!(
+            "http://localhost:{port}/api/w/{w_id}/workspaces/datatable_acl/main/{action}"
+        ))
+        .header("Authorization", format!("Bearer {token}"))
+        .json(&grant_select_on_public())
+        .send()
+        .await?)
+}
+
+/// A fork reaches the data table through a pointer: it may use it, never change what each role may
+/// touch on it — not even as an admin of the fork.
+#[cfg(all(feature = "private", feature = "enterprise"))]
+#[sqlx::test(migrations = "../migrations", fixtures("base", "datatable_roles"))]
+async fn a_fork_cannot_change_access_on_the_data_table_it_points_at(
+    db: Pool<Postgres>,
+) -> anyhow::Result<()> {
+    initialize_tracing().await;
+    let server = ApiServer::start(db.clone()).await?;
+    let port = server.addr.port();
+    for action in ["plan", "apply"] {
+        let resp = post_acl(port, "wm-fork-dt", action, "SECRET_TOKEN_2").await?;
+        assert_eq!(resp.status(), 401, "{action}: {}", resp.text().await?);
+    }
+    Ok(())
+}
+
+#[cfg(all(feature = "private", feature = "enterprise"))]
+#[sqlx::test(migrations = "../migrations", fixtures("base", "datatable_roles"))]
+async fn a_member_who_is_not_an_admin_cannot_change_access(
+    db: Pool<Postgres>,
+) -> anyhow::Result<()> {
+    initialize_tracing().await;
+    let server = ApiServer::start(db.clone()).await?;
+    let port = server.addr.port();
+    for action in ["plan", "apply"] {
+        let resp = post_acl(port, "test-workspace", action, "SECRET_TOKEN_2").await?;
+        assert_eq!(resp.status(), 401, "{action}: {}", resp.text().await?);
+    }
+    Ok(())
+}
+
+/// Not even reading, and not even on a data table that is not under roles — which any member
+/// reaches, so only the edition stands between them and the instance's credentials.
+#[cfg(not(all(feature = "private", feature = "enterprise")))]
+#[sqlx::test(migrations = "../migrations", fixtures("base", "datatable_roles"))]
+async fn only_the_enterprise_edition_has_the_access_editor(
+    db: Pool<Postgres>,
+) -> anyhow::Result<()> {
+    initialize_tracing().await;
+    sqlx::query(
+        "UPDATE workspace_settings
+         SET datatable = datatable #- '{datatables,main,permissions}'
+         WHERE workspace_id = 'test-workspace'",
+    )
+    .execute(&db)
+    .await?;
+    let server = ApiServer::start(db.clone()).await?;
+    let port = server.addr.port();
+
+    let read = reqwest::Client::new()
+        .get(format!(
+            "http://localhost:{port}/api/w/test-workspace/workspaces/datatable_acl/main?kind=database"
+        ))
+        .header("Authorization", "Bearer SECRET_TOKEN")
+        .send()
+        .await?;
+    let mut responses = vec![("read", read)];
+    for action in ["plan", "apply"] {
+        responses.push((
+            action,
+            post_acl(port, "test-workspace", action, "SECRET_TOKEN").await?,
+        ));
+    }
+    for (action, resp) in responses {
+        assert_eq!(resp.status(), 400, "{action}");
+        let body = resp.text().await?;
+        assert!(
+            body.contains("Data table roles are a Windmill Enterprise Edition feature"),
+            "{action}: {body}"
+        );
+    }
+    Ok(())
+}

backend/windmill-api-integration-tests/tests/fixtures/datatable_roles.sql

@@ -0,0 +1,45 @@
+-- A data table under roles in `test-workspace`, and a fork whose entry points at it rather than
+-- carrying a copy. `test-user-2` is a non-admin of the parent and an admin of the fork: the shape
+-- the pointer exists for.
+
+-- Empty registry: role provisioning grants CONNECT on every database named here, and the data
+-- table's `dt_main` is a name in workspace settings, not a database that exists.
+INSERT INTO global_settings (name, value) VALUES
+    ('custom_instance_pg_databases', '{"user_pwd": "pw", "databases": {}}'::jsonb)
+    ON CONFLICT (name) DO UPDATE SET value = EXCLUDED.value;
+
+INSERT INTO datatable_role (id, name, enabled, pwd) VALUES ('role1', 'analytics', true, 'pw');
+
+UPDATE workspace_settings SET datatable = '{
+    "datatables": {
+        "main": {
+            "database": {"resource_type": "instance", "resource_path": "dt_main"},
+            "permissions": {
+                "default_role": "role1",
+                "roles": {
+                    "admin": {"tenants": []},
+                    "role1": {"tenants": ["u/test-user-2", "g/analysts", "f/finance"]}
+                }
+            }
+        }
+    }
+}'::jsonb WHERE workspace_id = 'test-workspace';
+
+INSERT INTO group_ (workspace_id, name, summary, extra_perms) VALUES
+	('test-workspace', 'analysts', 'Analysts', '{}');
+INSERT INTO folder (workspace_id, name, display_name, owners, extra_perms) VALUES
+	('test-workspace', 'finance', 'finance', '{}', '{}');
+
+INSERT INTO workspace (id, name, owner, parent_workspace_id) VALUES
+	('wm-fork-dt', 'fork of test-workspace', 'test2@windmill.dev', 'test-workspace');
+INSERT INTO workspace_key (workspace_id, kind, key) VALUES ('wm-fork-dt', 'cloud', 'test-key');
+INSERT INTO group_ (workspace_id, name, summary, extra_perms) VALUES
+	('wm-fork-dt', 'all', 'All users', '{}');
+INSERT INTO usr (workspace_id, email, username, is_admin, role) VALUES
+	('wm-fork-dt', 'test2@windmill.dev', 'test-user-2', true, 'Admin');
+
+INSERT INTO workspace_settings (workspace_id, datatable) VALUES ('wm-fork-dt', '{
+    "datatables": {
+        "main": {"reference": {"workspace_id": "test-workspace", "datatable": "main"}}
+    }
+}'::jsonb);

backend/windmill-api-settings/Cargo.toml

@@ -11,7 +11,7 @@ path = "src/lib.rs"
 [features]
 default = []
 enterprise = ["license"]
-private = ["windmill-common/private"]
+private = ["windmill-common/private", "windmill-audit/private"]
 parquet = ["windmill-common/parquet", "windmill-object-store/parquet"]
 license = ["dep:rsa"]
 
@@ -19,6 +19,7 @@ license = ["dep:rsa"]
 windmill-ai = { workspace = true, default-features = false }
 windmill-alerting.workspace = true
 windmill-api-auth.workspace = true
+windmill-audit.workspace = true
 windmill-common = { workspace = true, default-features = false }
 axum.workspace = true
 anyhow.workspace = true

backend/windmill-api-settings/src/datatable_roles_oss.rs

@@ -0,0 +1,44 @@
+/*
+ * Author: Ruben Fiszel
+ * Copyright: Windmill Labs, Inc 2022
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the included NOTICE for copyright information and
+ * LICENSE-AGPL for a copy of the license.
+ */
+
+//! Where the data table role catalog endpoints come from: the enterprise implementation, or a
+//! refusal. Roles are an Enterprise Edition feature; see `windmill_common::datatable_roles_oss`.
+
+#[cfg(all(feature = "private", feature = "enterprise"))]
+pub(crate) use crate::datatable_roles_ee::{
+    create_datatable_role, delete_datatable_role, list_datatable_roles, update_datatable_role,
+};
+
+#[cfg(not(all(feature = "private", feature = "enterprise")))]
+pub(crate) use ce::*;
+
+// The routes stay registered so the API has one shape; each answers after authentication, before
+// anything is read.
+#[cfg(not(all(feature = "private", feature = "enterprise")))]
+mod ce {
+    use windmill_api_auth::ApiAuthed;
+    use windmill_common::{
+        datatable_roles_oss::datatable_roles_unavailable as unavailable, error::Result,
+    };
+
+    pub(crate) async fn list_datatable_roles(_authed: ApiAuthed) -> Result<String> {
+        Err(unavailable())
+    }
+
+    pub(crate) async fn create_datatable_role(_authed: ApiAuthed) -> Result<String> {
+        Err(unavailable())
+    }
+
+    pub(crate) async fn update_datatable_role(_authed: ApiAuthed) -> Result<String> {
+        Err(unavailable())
+    }
+
+    pub(crate) async fn delete_datatable_role(_authed: ApiAuthed) -> Result<String> {
+        Err(unavailable())
+    }
+}

backend/windmill-api-settings/src/lib.rs

@@ -17,6 +17,9 @@ mod audit_logs_s3;
 mod audit_logs_s3_backfill;
 #[cfg(feature = "parquet")]
 mod background_task;
+#[cfg(all(feature = "private", feature = "enterprise"))]
+mod datatable_roles_ee;
+mod datatable_roles_oss;
 #[cfg(feature = "private")]
 mod ee;
 pub mod ee_oss;
@@ -57,7 +60,7 @@ use windmill_common::{
     global_settings::{
         AI_CONFIG_SETTING, APP_WORKSPACED_ROUTE_SETTING, AUTOMATE_USERNAME_CREATION_SETTING,
         CRITICAL_ALERT_MUTE_UI_SETTING, CUSTOM_TAGS_SETTING, DEFAULT_TAGS_WORKSPACES_SETTING,
-        DISABLE_HUB_SETTING, EMAIL_DOMAIN_SETTING, ENV_SETTINGS,
+        DISABLE_HUB_SETTING, EMAIL_DOMAIN_SETTING, ENV_SETTINGS, EXTERNAL_INSTANCE_PG_SETTING,
         GITHUB_APP_WEBHOOK_BASE_URL_SETTING, HTTP_ROUTE_DEFAULT_ALLOWED_ORIGINS_SETTING,
         HTTP_ROUTE_WORKSPACED_ROUTE_SETTING, HUB_ACCESSIBLE_URL_SETTING, HUB_BASE_URL_SETTING,
         INSTANCE_BANNER_SETTING, MAX_RETENTION_OVERRIDE_WORKSPACES,
@@ -151,10 +154,36 @@ pub fn global_service() -> Router {
             "/list_custom_instance_pg_databases",
             post(list_custom_instance_pg_databases),
         )
+        .route(
+            "/datatable_roles",
+            get(datatable_roles_oss::list_datatable_roles)
+                .post(datatable_roles_oss::create_datatable_role),
+        )
+        .route(
+            "/datatable_roles/{id}",
+            post(datatable_roles_oss::update_datatable_role)
+                .delete(datatable_roles_oss::delete_datatable_role),
+        )
         .route(
             "/refresh_custom_instance_user_pwd",
             post(refresh_custom_instance_user_pwd),
         )
+        .route(
+            "/external_instance_pg/status",
+            get(get_external_instance_pg_status),
+        )
+        .route(
+            "/external_instance_pg/setup",
+            post(setup_external_instance_pg),
+        )
+        .route(
+            "/external_instance_pg/databases",
+            get(list_external_instance_pg_databases),
+        )
+        .route(
+            "/external_instance_pg/databases/{name}",
+            post(create_external_instance_pg_database).delete(drop_external_instance_pg_database),
+        )
         .route(
             "/setup_custom_instance_pg_database/{name}",
             post(setup_custom_instance_pg_database),
@@ -864,6 +893,14 @@ pub async fn set_global_setting_internal(
         )));
     }
 
+    if key == EXTERNAL_INSTANCE_PG_SETTING {
+        return windmill_common::external_instance_pg::write_external_instance_pg_setting(
+            db,
+            Some(&value),
+        )
+        .await;
+    }
+
     run_setting_pre_write_hook(db, &key, &value).await?;
 
     match value {
@@ -1245,7 +1282,7 @@ async fn set_instance_config(
     let desired_map = desired.global_settings.to_settings_map();
     if !desired_map.is_empty() {
         let current_map = current.global_settings.to_settings_map();
-        let settings_diff =
+        let mut settings_diff =
             instance_config::diff_global_settings(&current_map, &desired_map, ApplyMode::Merge);
         let ai_config_changed = settings_diff
             .upserts
@@ -1274,8 +1311,15 @@ async fn set_instance_config(
         }
 
         for (key, value) in &settings_diff.upserts {
-            run_setting_pre_write_hook(&db, key, value).await?;
+            if key != EXTERNAL_INSTANCE_PG_SETTING {
+                run_setting_pre_write_hook(&db, key, value).await?;
+            }
         }
+        windmill_common::external_instance_pg::write_external_instance_pg_from_diff(
+            &db,
+            &mut settings_diff,
+        )
+        .await?;
 
         instance_config::apply_settings_diff(&db, &settings_diff)
             .await
@@ -1634,6 +1678,8 @@ struct CustomInstanceDb {
     tag: Option<String>,
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
     used_by_workspaces: Vec<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    workspace_id: Option<String>,
 }
 
 #[derive(Deserialize, Debug, Serialize, Default)]
@@ -1730,6 +1776,135 @@ async fn refresh_custom_instance_user_pwd(
     Ok(Json(()))
 }
 
+async fn get_external_instance_pg_status(
+    authed: ApiAuthed,
+    Extension(db): Extension<DB>,
+) -> JsonResult<windmill_common::external_instance_pg::ExternalInstancePgStatus> {
+    require_super_admin(&db, &authed).await?;
+    Ok(Json(
+        windmill_common::external_instance_pg::external_instance_pg_status(&db).await?,
+    ))
+}
+
+#[derive(Deserialize)]
+struct SetupExternalInstancePgBody {
+    #[serde(default)]
+    rotate_passwords: bool,
+}
+
+async fn setup_external_instance_pg(
+    authed: ApiAuthed,
+    Extension(db): Extension<DB>,
+    Json(body): Json<SetupExternalInstancePgBody>,
+) -> JsonResult<windmill_common::external_instance_pg::ExternalInstancePgSetupReport> {
+    require_super_admin(&db, &authed).await?;
+    let report = windmill_common::external_instance_pg::setup_external_instance_pg_unchecked(
+        &db,
+        body.rotate_passwords,
+    )
+    .await?;
+    let rotated = body.rotate_passwords.to_string();
+    let success = report.success.to_string();
+    windmill_audit::audit_oss::audit_log(
+        &db,
+        &authed,
+        "settings.setup_external_instance_pg",
+        windmill_audit::ActionKind::Update,
+        "global",
+        Some(&authed.email),
+        Some(
+            [
+                ("rotate_passwords", rotated.as_str()),
+                ("success", success.as_str()),
+            ]
+            .into(),
+        ),
+    )
+    .await?;
+    Ok(Json(report))
+}
+
+#[derive(Serialize)]
+struct ExternalInstancePgDatabase {
+    #[serde(flatten)]
+    status: windmill_common::instance_config::CustomInstanceDb,
+    used_by_workspaces: Vec<String>,
+}
+
+async fn list_external_instance_pg_databases(
+    authed: ApiAuthed,
+    Extension(db): Extension<DB>,
+) -> JsonResult<std::collections::BTreeMap<String, ExternalInstancePgDatabase>> {
+    require_super_admin(&db, &authed).await?;
+    let databases = windmill_common::external_instance_pg::external_instance_databases(&db).await?;
+    let mut usages =
+        windmill_common::external_instance_pg::external_instance_database_usages(&db).await?;
+    Ok(Json(
+        databases
+            .into_iter()
+            .map(|(name, status)| {
+                let used_by_workspaces = usages.remove(&name).unwrap_or_default();
+                (
+                    name,
+                    ExternalInstancePgDatabase {
+                        status,
+                        used_by_workspaces: used_by_workspaces.into_iter().collect(),
+                    },
+                )
+            })
+            .collect(),
+    ))
+}
+
+async fn create_external_instance_pg_database(
+    authed: ApiAuthed,
+    Extension(db): Extension<DB>,
+    Path(dbname): Path<String>,
+    Json(body): Json<SetupCustomInstanceDbBody>,
+) -> JsonResult<()> {
+    require_super_admin(&db, &authed).await?;
+    let tag = body.tag.as_deref().unwrap_or("datatable");
+    windmill_common::external_instance_pg::create_external_instance_database_unchecked(
+        &db, &dbname, tag, None,
+    )
+    .await?;
+    windmill_audit::audit_oss::audit_log(
+        &db,
+        &authed,
+        "settings.create_external_instance_pg_database",
+        windmill_audit::ActionKind::Create,
+        "global",
+        Some(&authed.email),
+        Some([("dbname", dbname.as_str()), ("tag", tag)].into()),
+    )
+    .await?;
+    Ok(Json(()))
+}
+
+async fn drop_external_instance_pg_database(
+    authed: ApiAuthed,
+    Extension(db): Extension<DB>,
+    Path(dbname): Path<String>,
+) -> JsonResult<()> {
+    require_super_admin(&db, &authed).await?;
+    // A data table naming a dropped database fails on every job, far from the drop that caused it.
+    windmill_common::external_instance_pg::drop_external_instance_database_unchecked(
+        &db, &dbname, None,
+    )
+    .await?;
+    windmill_audit::audit_oss::audit_log(
+        &db,
+        &authed,
+        "settings.drop_external_instance_pg_database",
+        windmill_audit::ActionKind::Delete,
+        "global",
+        Some(&authed.email),
+        Some([("dbname", dbname.as_str())].into()),
+    )
+    .await?;
+    Ok(Json(()))
+}
+
 #[derive(Deserialize)]
 struct SetupCustomInstanceDbBody {
     tag: Option<String>,
@@ -1741,12 +1916,31 @@ async fn setup_custom_instance_pg_database(
     Path(dbname): Path<String>,
     Json(body): Json<SetupCustomInstanceDbBody>,
 ) -> JsonResult<CustomInstanceDb> {
+    // Before anything is recorded: the status written below replaces the registry entry, and with it
+    // the workspace a fork copy is reserved for.
+    require_super_admin(&db, &authed).await?;
+    // A re-run keeps the fork reservation: without it, the workspace the copy was made for could no
+    // longer import into it or finish its fork.
+    let workspace_id = sqlx::query_scalar::<_, Option<String>>(
+        "SELECT value->'databases'->$1->>'workspace_id' FROM global_settings
+         WHERE name = 'custom_instance_pg_databases'",
+    )
+    .bind(&dbname)
+    .fetch_optional(&db)
+    .await?
+    .flatten();
     let mut logs = CustomInstanceDbLogs::default();
     let result = setup_custom_instance_pg_database_inner(authed, &db, &dbname, &mut logs).await;
     let success = result.is_ok();
     let error = result.err().map(|e| e.to_string());
-    let status =
-        CustomInstanceDb { logs, success, error, tag: body.tag, used_by_workspaces: vec![] };
+    let status = CustomInstanceDb {
+        logs,
+        success,
+        error,
+        tag: body.tag,
+        used_by_workspaces: vec![],
+        workspace_id,
+    };
     let status_json = serde_json::to_value(&status).map_err(to_anyhow)?;
     // Save that the database was setup successfully
     sqlx::query!(

backend/windmill-api-users/src/users.rs

@@ -1703,14 +1703,25 @@ async fn delete_user(
         .await?;
     windmill_common::user_drafts::delete_drafts_of_email(&mut *tx, &email_to_delete).await?;
 
-    let usernames = sqlx::query_scalar!(
-        "DELETE FROM usr WHERE email = $1 RETURNING username",
+    let memberships = sqlx::query!(
+        "DELETE FROM usr WHERE email = $1 RETURNING username, workspace_id",
         &email_to_delete
     )
     .fetch_all(&mut *tx)
     .await?;
 
-    for username in usernames {
+    for row in memberships {
+        let username = row.username;
+        // A tenant list names a principal of its workspace, so the name has to be freed in every
+        // workspace this account belonged to: a later account taking the username would otherwise
+        // inherit the data table access it had.
+        windmill_common::workspaces::remove_datatable_tenant_in_workspace(
+            &mut tx,
+            &row.workspace_id,
+            &format!("u/{username}"),
+        )
+        .await?;
+
         sqlx::query!("DELETE FROM password WHERE email = $1", &email_to_delete)
             .execute(&mut *tx)
             .await?;
@@ -2456,6 +2467,15 @@ pub async fn delete_workspace_user_internal(
     tx: &mut Transaction<'_, Postgres>,
     authed: Option<&ApiAuthed>, // None for system operations
 ) -> Result<()> {
+    // Same reasoning as the `extra_perms` sweep below: a freed username must not stay named
+    // anywhere that grants access, tenant lists included.
+    windmill_common::workspaces::remove_datatable_tenant_in_workspace(
+        tx,
+        w_id,
+        &format!("u/{username_to_delete}"),
+    )
+    .await?;
+
     // ---- Clean up extra_perms referencing this user ----
     let extra_perms_tables = [
         "script",
@@ -3965,6 +3985,12 @@ async fn leave_workspace(
 ) -> Result<String> {
     forbid_job_token_account_destruction(&authed)?;
     let mut tx = db.begin().await?;
+    windmill_common::workspaces::remove_datatable_tenant_in_workspace(
+        &mut tx,
+        &w_id,
+        &format!("u/{}", authed.username),
+    )
+    .await?;
     sqlx::query!(
         "DELETE FROM usr WHERE workspace_id = $1 AND username = $2",
         &w_id,

backend/windmill-api-workspaces/src/datatable_acl_oss.rs

@@ -0,0 +1,44 @@
+/*
+ * Author: Ruben Fiszel
+ * Copyright: Windmill Labs, Inc 2022
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the included NOTICE for copyright information and
+ * LICENSE-AGPL for a copy of the license.
+ */
+
+//! Where the ACL planner comes from: the enterprise one, or a refusal.
+//!
+//! Data table roles are an Enterprise Edition feature, and so is everything here — reading who
+//! owns what included. `private` alone is not that edition — community builds carry it — so the
+//! planner is behind `enterprise` as well.
+
+#[cfg(all(feature = "private", feature = "enterprise"))]
+pub(crate) use crate::datatable_acl_ee::plan_statements;
+
+#[cfg(all(feature = "private", feature = "enterprise"))]
+pub(crate) fn ensure_datatable_acl_available() -> windmill_common::error::Result<()> {
+    Ok(())
+}
+
+#[cfg(not(all(feature = "private", feature = "enterprise")))]
+use {
+    crate::datatable_acl::{AclChange, AclPlan, AclTarget, CatalogFacts},
+    windmill_common::{datatable_roles_oss::datatable_roles_unavailable, error::Result},
+};
+
+/// Checked first by every ACL route, before anything is read or connected to.
+#[cfg(not(all(feature = "private", feature = "enterprise")))]
+pub(crate) fn ensure_datatable_acl_available() -> Result<()> {
+    Err(datatable_roles_unavailable())
+}
+
+#[cfg(not(all(feature = "private", feature = "enterprise")))]
+pub(crate) fn plan_statements(
+    _target: &AclTarget,
+    _change: &AclChange,
+    _dbname: &str,
+    _pg_role: &str,
+    _facts: &CatalogFacts,
+) -> Result<AclPlan> {
+    Err(datatable_roles_unavailable())
+}

backend/windmill-api-workspaces/src/datatable_migrations.rs

@@ -11,7 +11,7 @@
 //! to keep that file focused on core workspace configuration.
 
 use crate::workspaces::{
-    is_instance_datatable, pg_dump_database, strip_unreplayable_dump_lines, ItemComparison,
+    managed_datatable_kind, pg_dump_database, strip_unreplayable_dump_lines, ItemComparison,
     PgDumpOptions,
 };
 
@@ -30,6 +30,7 @@ use windmill_api_auth::{require_super_admin, ApiAuthed};
 use windmill_api_jobs::run_wait_result_internal;
 use windmill_audit::audit_oss::audit_log;
 use windmill_audit::ActionKind;
+use windmill_common::datatable_roles::ADMIN_DATATABLE_ROLE;
 use windmill_common::db::UserDB;
 use windmill_common::error::{pg_error_message, Error, JsonResult, Result};
 use windmill_common::jobs::{JobPayload, RawCode};
@@ -38,7 +39,11 @@ use windmill_common::runnable_settings::{ConcurrencySettingsWithCustom, Debounci
 use windmill_common::scripts::ScriptLang;
 use windmill_common::users::username_to_permissioned_as;
 use windmill_common::worker::to_raw_value;
-use windmill_common::workspaces::get_datatable_resource_from_db_unchecked;
+use windmill_common::worker::SqlAnnotations;
+use windmill_common::workspaces::{
+    ensure_can_use_datatable_role, ensure_datatable_admin_access,
+    get_datatable_resource_from_db_unchecked, resolve_governing_datatable, DatatableAccess,
+};
 use windmill_common::{PgDatabase, DB};
 use windmill_git_sync::{
     handle_deployment_metadata, handle_deployment_metadata_batch, DeployedObject,
@@ -86,6 +91,42 @@ pub(crate) fn routes() -> Router {
         )
 }
 
+/// Refuse a migration whose role this caller may not use, before a job is pushed or a version
+/// recorded.
+///
+/// A migration that declares `-- role <name>` runs as that role, so the caller has to be one of its
+/// tenants. One that declares none runs as `admin` and reaches every object in the database
+/// whatever the roles grant, so it is for the admins of the workspace that governs the data table
+/// — a fork can run a migration under a role it holds, never a migration under `admin`.
+///
+/// The executor re-checks the role when it resolves the connection, so this is not the boundary. It
+/// is what makes the refusal legible: which migration, and which role.
+async fn ensure_migration_role_allowed(
+    db: &DB,
+    w_id: &str,
+    datatable_name: &str,
+    authed: &ApiAuthed,
+    sql: &str,
+    timestamp: i64,
+    name: &str,
+) -> Result<()> {
+    let context = format!("Migration {timestamp} ({name})");
+    let access = DatatableAccess::Authed(authed.to_authed_ref());
+    match SqlAnnotations::datatable_role(sql)? {
+        Some(role) => {
+            ensure_can_use_datatable_role(db, w_id, datatable_name, Some(&role), &access, &context)
+                .await
+        }
+        None => ensure_datatable_admin_access(db, w_id, datatable_name, &access)
+            .await
+            .map_err(|e| {
+                Error::NotAuthorized(format!(
+                    "{context} declares no role, so it would run as admin. {e}"
+                ))
+            }),
+    }
+}
+
 #[derive(Serialize)]
 struct AppliedMigration {
     version: i64,
@@ -128,7 +169,18 @@ async fn datatable_database_arg(
     .await?
     .ok_or_else(|| Error::internal_err(format!("datatable {datatable_name} not found")))?;
 
-    Ok(to_raw_value(&format!("datatable://{datatable_name}")))
+    // `?role=admin` rather than a bare reference, so a migration that declares no `-- role` runs
+    // as the connection that owns the schema instead of falling through to the data table's
+    // default role — which is what `ensure_migration_role_allowed` gated it as, and which is the
+    // only role a DDL statement can be expected to succeed under. A migration that does declare a
+    // role overrides this: the annotation wins over the reference.
+    //
+    // A legacy name containing `?` cannot be migrated through this reference: the appended query
+    // makes it neither an exact name nor a parseable one. Accepted on purpose, since such names can
+    // no longer be created and none are expected to carry migrations.
+    Ok(to_raw_value(&format!(
+        "datatable://{datatable_name}?role={ADMIN_DATATABLE_ROLE}"
+    )))
 }
 
 /// Run a migration's SQL as a normal Windmill `postgresql` job, permissioned as
@@ -384,6 +436,11 @@ async fn run_datatable_migrations(
     Path((w_id, datatable_name)): Path<(String, String)>,
     Query(query): Query<RunDatatableMigrationsQuery>,
 ) -> JsonResult<RunDatatableMigrationsResult> {
+    // Before the admin connection is opened at all: the bookkeeping below is created and read
+    // through it, so a caller no role covers must be refused here rather than after the fact.
+    crate::datatable_permissions::ensure_reaches_datatable(&db, &w_id, &datatable_name, &authed)
+        .await?;
+
     audit_log(
         &db,
         &authed,
@@ -440,6 +497,16 @@ async fn run_datatable_migrations(
         if applied_versions.contains(&m.timestamp) {
             continue;
         }
+        ensure_migration_role_allowed(
+            &db,
+            &w_id,
+            &datatable_name,
+            &authed,
+            &m.code_up,
+            m.timestamp,
+            &m.name,
+        )
+        .await?;
         run_datatable_migration_job(&db, &user_db, &authed, &w_id, &database_arg, &m.code_up)
             .await
             .map_err(|e| {
@@ -506,6 +573,11 @@ async fn rollback_datatable_migrations(
     Path((w_id, datatable_name)): Path<(String, String)>,
     Query(query): Query<RollbackDatatableMigrationsQuery>,
 ) -> JsonResult<RollbackDatatableMigrationsResult> {
+    // Before the admin connection is opened at all: the bookkeeping below is created and read
+    // through it, so a caller no role covers must be refused here rather than after the fact.
+    crate::datatable_permissions::ensure_reaches_datatable(&db, &w_id, &datatable_name, &authed)
+        .await?;
+
     audit_log(
         &db,
         &authed,
@@ -588,6 +660,17 @@ async fn rollback_datatable_migrations(
         ))
     })?;
 
+    ensure_migration_role_allowed(
+        &db,
+        &w_id,
+        &datatable_name,
+        &authed,
+        &code_down,
+        version,
+        &definition.name,
+    )
+    .await?;
+
     let database_arg = datatable_database_arg(&db, &w_id, &datatable_name).await?;
     run_datatable_migration_job(&db, &user_db, &authed, &w_id, &database_arg, &code_down)
         .await
@@ -748,10 +831,15 @@ async fn read_applied_datatable_versions(
 
 /// List a data table's migrations annotated with whether each has been applied.
 async fn datatable_migrations_status(
-    _authed: ApiAuthed,
+    authed: ApiAuthed,
     Extension(db): Extension<DB>,
     Path((w_id, datatable_name)): Path<(String, String)>,
 ) -> JsonResult<DatatableMigrationsStatusResult> {
+    // Reads `_wm_migrations` through the data table's admin connection, so it answers to the same
+    // question as running one: may you reach this data table at all.
+    crate::datatable_permissions::ensure_reaches_datatable(&db, &w_id, &datatable_name, &authed)
+        .await?;
+
     let enabled = datatable_migrations_enabled(&db, &w_id, &datatable_name).await?;
     if !enabled {
         return Ok(Json(DatatableMigrationsStatusResult {
@@ -1431,6 +1519,15 @@ async fn generate_initial_datatable_migration(
     Extension(db): Extension<DB>,
     Path((w_id, datatable_name)): Path<(String, String)>,
 ) -> JsonResult<DatatableMigration> {
+    // Returns a `pg_dump` of the whole schema and writes into the data table's own bookkeeping, so
+    // it answers to the workspace that governs it rather than to whoever is asking.
+    ensure_datatable_admin_access(
+        &db,
+        &w_id,
+        &datatable_name,
+        &DatatableAccess::Authed(authed.to_authed_ref()),
+    )
+    .await?;
     validate_datatable_path_segment(&datatable_name)?;
     ensure_datatable_migrations_enabled(&db, &w_id, &datatable_name).await?;
 
@@ -1459,7 +1556,9 @@ async fn generate_initial_datatable_migration(
     // without what a replay elsewhere cannot run: the replaying user owns none of this
     // database's objects, and the grants Windmill plants in an instance database (`ALTER
     // DEFAULT PRIVILEGES FOR ROLE ...`) fail even replaying onto the same server.
-    let no_acl = is_instance_datatable(&db, &w_id, &datatable_name).await?;
+    let no_acl = managed_datatable_kind(&db, &w_id, &datatable_name)
+        .await?
+        .is_some();
     let dump_file = pg_dump_database(
         &pg_db,
         PgDumpOptions {
@@ -1601,9 +1700,21 @@ pub(crate) struct DatatableRename {
     pub(crate) to: String,
 }
 
-async fn resolve_datatable_pg(db: &DB, w_id: &str, datatable: &str) -> Result<PgDatabase> {
+/// The database whose `_wm_migrations` a rename or delete of `datatable` in `w_id` should touch —
+/// `None` when that is somebody else's.
+///
+/// A fork's entry points at the workspace that governs the data table, so renaming or removing it
+/// changes what the fork calls the data table and nothing more. Following the pointer here would
+/// let a fork admin relabel or wipe the *governing* workspace's migration bookkeeping through
+/// their own settings form, and the parent would then re-run every migration from zero.
+async fn resolve_datatable_pg(db: &DB, w_id: &str, datatable: &str) -> Result<Option<PgDatabase>> {
+    let governing = resolve_governing_datatable(db, w_id, datatable).await?;
+    if governing.workspace_id != w_id {
+        return Ok(None);
+    }
     let db_resource = get_datatable_resource_from_db_unchecked(db, w_id, datatable).await?;
     serde_json::from_value(db_resource)
+        .map(Some)
         .map_err(|e| Error::internal_err(format!("Failed to parse database credentials: {}", e)))
 }
 
@@ -1621,7 +1732,9 @@ fn ignore_missing_wm_migrations(e: tokio_postgres::Error) -> Result<()> {
 
 /// Drop a data table's rows from its own database's `_wm_migrations`.
 async fn remote_forget_datatable_migrations(db: &DB, w_id: &str, datatable: &str) -> Result<()> {
-    let pg_db = resolve_datatable_pg(db, w_id, datatable).await?;
+    let Some(pg_db) = resolve_datatable_pg(db, w_id, datatable).await? else {
+        return Ok(());
+    };
     let (client, connection) = pg_db.connect(Some(db)).await?;
     tokio::spawn(async move {
         let _ = connection.await;
@@ -1646,7 +1759,9 @@ async fn remote_rename_datatable_migrations(
     from: &str,
     to: &str,
 ) -> Result<()> {
-    let pg_db = resolve_datatable_pg(db, w_id, resolve_by).await?;
+    let Some(pg_db) = resolve_datatable_pg(db, w_id, resolve_by).await? else {
+        return Ok(());
+    };
     let (client, connection) = pg_db.connect(Some(db)).await?;
     tokio::spawn(async move {
         let _ = connection.await;

backend/windmill-api-workspaces/src/datatable_permissions.rs

@@ -0,0 +1,79 @@
+/*
+ * Author: Ruben Fiszel
+ * Copyright: Windmill Labs, Inc 2022
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the included NOTICE for copyright information and
+ * LICENSE-AGPL for a copy of the license.
+ */
+
+//! Who may connect to a data table as which role.
+//!
+//! The decision lives on the data table entry of the workspace that governs it, which is not
+//! necessarily the workspace asking: a fork's entry points at its parent's, and everything here
+//! resolves through that pointer first. Nothing in this module runs SQL against the data table —
+//! a save is tenant lists and a default, and the Postgres roles themselves are the instance
+//! catalog's business.
+
+use axum::{routing::get, Router};
+
+use windmill_api_auth::ApiAuthed;
+use windmill_common::error::Result;
+use windmill_common::workspaces::GoverningDatatable;
+use windmill_common::DB;
+
+use crate::datatable_permissions_oss as roles;
+
+pub(crate) fn routes() -> Router {
+    Router::new()
+        .route(
+            "/datatable_permissions/{datatable_name}",
+            get(roles::get_datatable_permissions).post(roles::set_datatable_permissions),
+        )
+        .route(
+            "/datatable_usable_roles/{datatable_name}",
+            get(roles::list_usable_datatable_roles),
+        )
+}
+
+/// Administering a data table — its permissions, its migrations that declare no role, its exports
+/// — is for the admins of the workspace that governs it. A fork can use the data table; it never
+/// administers it.
+// The gate for whatever administers a data table under roles, which the routes of this module alone
+// do not always reach.
+#[allow(dead_code)]
+pub(crate) async fn ensure_governs_datatable(
+    db: &DB,
+    authed: &ApiAuthed,
+    w_id: &str,
+    governing: &GoverningDatatable,
+) -> Result<()> {
+    roles::ensure_governs_datatable(db, authed, w_id, governing).await
+}
+
+/// Refuse a caller that no tenant of this data table covers.
+///
+/// The bookkeeping endpoints below open the data table's `admin` connection to read or create
+/// `_wm_migrations` before they know which migration will run — so without this, someone covered
+/// by no role at all can still force admin-backed reads and writes on a database they may not
+/// touch. It asks only "may you reach this data table as anything"; which role a given migration
+/// runs as is still decided per migration, and by the executor after that.
+pub(crate) async fn ensure_reaches_datatable(
+    db: &DB,
+    w_id: &str,
+    datatable_name: &str,
+    authed: &ApiAuthed,
+) -> Result<()> {
+    roles::ensure_reaches_datatable(db, w_id, datatable_name, authed).await
+}
+
+/// [`ensure_reaches_datatable`] against an entry already resolved, for a caller that goes on to
+/// connect from that same entry.
+pub(crate) async fn ensure_reaches_governing_datatable(
+    db: &DB,
+    w_id: &str,
+    datatable_name: &str,
+    governing: &GoverningDatatable,
+    authed: &ApiAuthed,
+) -> Result<()> {
+    roles::ensure_reaches_governing_datatable(db, w_id, datatable_name, governing, authed).await
+}

backend/windmill-api-workspaces/src/datatable_permissions_oss.rs

@@ -0,0 +1,112 @@
+/*
+ * Author: Ruben Fiszel
+ * Copyright: Windmill Labs, Inc 2022
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the included NOTICE for copyright information and
+ * LICENSE-AGPL for a copy of the license.
+ */
+
+//! Where the data table permissions endpoints and their gates come from: the enterprise
+//! implementation, or a refusal. Roles are an Enterprise Edition feature; see
+//! `windmill_common::datatable_roles_oss`.
+
+#[cfg(all(feature = "private", feature = "enterprise"))]
+pub(crate) use crate::datatable_permissions_ee::{
+    ensure_governs_datatable, ensure_reaches_datatable, ensure_reaches_governing_datatable,
+    get_datatable_permissions, list_usable_datatable_roles, set_datatable_permissions,
+    usable_datatable_roles,
+};
+
+#[cfg(not(all(feature = "private", feature = "enterprise")))]
+pub(crate) use ce::*;
+
+#[cfg(not(all(feature = "private", feature = "enterprise")))]
+mod ce {
+    use windmill_api_auth::ApiAuthed;
+    use windmill_common::{
+        datatable_roles_oss::datatable_roles_unavailable as unavailable,
+        error::Result,
+        workspaces::{resolve_governing_datatable, GoverningDatatable},
+        DB,
+    };
+
+    /// Nobody administers a data table's roles without them.
+    #[allow(dead_code)]
+    pub(crate) async fn ensure_governs_datatable(
+        _db: &DB,
+        _authed: &ApiAuthed,
+        _w_id: &str,
+        _governing: &GoverningDatatable,
+    ) -> Result<()> {
+        Err(unavailable())
+    }
+
+    /// A data table not under roles is reached as it was before roles existed. One under roles is
+    /// refused: no role of it can be connected as.
+    pub(crate) async fn ensure_reaches_datatable(
+        db: &DB,
+        w_id: &str,
+        datatable_name: &str,
+        _authed: &ApiAuthed,
+    ) -> Result<()> {
+        let governing = resolve_governing_datatable(db, w_id, datatable_name).await?;
+        if governing.datatable.permissions.is_none() {
+            Ok(())
+        } else {
+            Err(unavailable())
+        }
+    }
+
+    pub(crate) async fn ensure_reaches_governing_datatable(
+        _db: &DB,
+        _w_id: &str,
+        _datatable_name: &str,
+        governing: &GoverningDatatable,
+        _authed: &ApiAuthed,
+    ) -> Result<()> {
+        if governing.datatable.permissions.is_none() {
+            Ok(())
+        } else {
+            Err(unavailable())
+        }
+    }
+
+    // The routes stay registered so the API has one shape; each answers after authentication,
+    // before anything is read.
+
+    pub(crate) async fn get_datatable_permissions(_authed: ApiAuthed) -> Result<String> {
+        Err(unavailable())
+    }
+
+    pub(crate) async fn set_datatable_permissions(_authed: ApiAuthed) -> Result<String> {
+        Err(unavailable())
+    }
+
+    pub(crate) async fn list_usable_datatable_roles(_authed: ApiAuthed) -> Result<String> {
+        Err(unavailable())
+    }
+
+    pub(crate) struct UsableDatatableRoles {
+        pub(crate) permissioned: bool,
+        pub(crate) roles: Vec<String>,
+        pub(crate) default_role: String,
+    }
+
+    /// A data table not under roles is used as `admin`, as before roles existed. One under roles
+    /// is refused: no role of it can be connected as.
+    pub(crate) async fn usable_datatable_roles(
+        _db: &DB,
+        _authed: &ApiAuthed,
+        _w_id: &str,
+        governing: &GoverningDatatable,
+    ) -> Result<UsableDatatableRoles> {
+        if governing.datatable.permissions.is_some() {
+            return Err(unavailable());
+        }
+        Ok(UsableDatatableRoles {
+            permissioned: false,
+            roles: vec![],
+            default_role: windmill_common::datatable_roles::ADMIN_DATATABLE_ROLE.to_string(),
+        })
+    }
+}

backend/windmill-api-workspaces/src/lib.rs

@@ -1,7 +1,11 @@
 #[cfg(feature = "parquet")]
 pub mod ai_session_backups;
 pub mod data_metrics;
+pub mod datatable_acl;
+pub mod datatable_acl_oss;
 pub mod datatable_migrations;
+pub mod datatable_permissions;
+pub mod datatable_permissions_oss;
 pub mod deployment_requests;
 pub mod workspaces;
 pub mod workspaces_extra;
@@ -9,3 +13,9 @@ pub mod workspaces_oss;
 
 #[cfg(feature = "private")]
 pub mod workspaces_ee;
+
+#[cfg(all(feature = "private", feature = "enterprise"))]
+pub mod datatable_acl_ee;
+
+#[cfg(all(feature = "private", feature = "enterprise"))]
+pub mod datatable_permissions_ee;

backend/windmill-api-workspaces/src/workspaces_extra.rs

@@ -110,6 +110,21 @@ pub(crate) async fn change_workspace_id(
     .execute(&mut *tx)
     .await?;
 
+    // A fork copy reserved for the old id would otherwise be unreachable: its creator cannot
+    // import into it or finish its fork under the new id, and nothing else would ever drop it.
+    sqlx::query(
+        r#"UPDATE global_settings SET value = jsonb_set(value, '{databases}', (
+               SELECT COALESCE(jsonb_object_agg(k, CASE WHEN v->>'workspace_id' = $1
+                   THEN jsonb_set(v, '{workspace_id}', to_jsonb($2::text)) ELSE v END), '{}'::jsonb)
+               FROM jsonb_each(COALESCE(value->'databases', '{}'::jsonb)) AS e(k, v)
+           ))
+           WHERE name = 'custom_instance_pg_databases'"#,
+    )
+    .bind(&old_id)
+    .bind(&rw.new_id)
+    .execute(&mut *tx)
+    .await?;
+
     // Duplicate workspace settings (keep copy in old workspace for reference)
     info!("Duplicating workspace_settings table");
     sqlx::query!(
@@ -492,6 +507,30 @@ pub(crate) async fn change_workspace_id(
     .fetch_all(&mut *tx)
     .await?;
 
+    // A fork's data table entry names the workspace that governs it by id, so the rename has to
+    // follow there too — anywhere, not just in the reparented children: a detached workspace can
+    // point at this one without being its fork. Left behind, the pointer resolves to the archived
+    // shell and every job through it stops.
+    info!("Re-pointing data table references to the new workspace id");
+    sqlx::query!(
+        r#"UPDATE workspace_settings ws
+           SET datatable = (
+               SELECT jsonb_set(ws.datatable, '{datatables}', jsonb_object_agg(
+                   dt.key,
+                   CASE WHEN dt.value->'reference'->>'workspace_id' = $2
+                       THEN jsonb_set(dt.value, '{reference,workspace_id}', to_jsonb($1::text))
+                       ELSE dt.value END
+               ))
+               FROM jsonb_each(ws.datatable->'datatables') dt
+           )
+           WHERE jsonb_typeof(ws.datatable->'datatables') = 'object'
+             AND ws.datatable::text LIKE '%"reference"%'"#,
+        &rw.new_id,
+        &old_id,
+    )
+    .execute(&mut *tx)
+    .await?;
+
     info!("Updating workspace_protection_rule table");
     sqlx::query!(
         "UPDATE workspace_protection_rule SET workspace_id = $1 WHERE workspace_id = $2",
@@ -971,6 +1010,22 @@ pub(crate) async fn delete_workspace(
     // but the destructive cleanup itself runs only after the commit below: a delete that
     // fails mid-way must never leave a live workspace with its fork data destroyed and no
     // registry row to retry from. Read-only: nothing is dropped here.
+    // Read before the delete: another workspace's data table entry can point at one of this
+    // workspace's, and deleting the workspace it names leaves that pointer resolving to nothing.
+    // Nothing sweeps them — turning them back into copies would hand each fork the database
+    // outright — so the deleter is told which data tables they just stranded.
+    let stranded_pointers = sqlx::query!(
+        r#"SELECT ws.workspace_id AS "workspace_id!", dt.key AS "datatable!"
+           FROM workspace_settings ws
+           CROSS JOIN LATERAL jsonb_each(COALESCE(ws.datatable->'datatables', '{}'::jsonb)) dt
+           WHERE dt.value->'reference'->>'workspace_id' = $1
+           ORDER BY ws.workspace_id, dt.key"#,
+        &w_id,
+    )
+    .fetch_all(&db)
+    .await
+    .unwrap_or_default();
+
     let fork_ducklake_cleanups = prepare_fork_ducklake_cleanups(&db, &w_id, None)
         .await
         .unwrap_or_else(|e| {
@@ -1289,7 +1344,23 @@ pub(crate) async fn delete_workspace(
         tracing::warn!("failed to broadcast fork lineage change: {e:#}");
     }
 
-    Ok(format!("Deleted workspace {}", &w_id))
+    if stranded_pointers.is_empty() {
+        Ok(format!("Deleted workspace {}", &w_id))
+    } else {
+        let stranded = stranded_pointers
+            .iter()
+            .map(|r| format!("{}/{}", r.workspace_id, r.datatable))
+            .collect::<Vec<_>>()
+            .join(", ");
+        Ok(format!(
+            concat!(
+                "Deleted workspace {}. These data tables were governed by it and no longer ",
+                "resolve: {}. Their databases still exist; a superadmin can point them at ",
+                "another workspace's data table."
+            ),
+            &w_id, stranded
+        ))
+    }
 }
 
 #[derive(Deserialize)]
@@ -1343,15 +1414,18 @@ pub async fn drop_forked_datatable_databases(
     let mut errors: Vec<String> = Vec::new();
 
     for dt_name in &req.datatable_names {
-        let dt = match datatables.get(dt_name) {
-            Some(dt) if dt.forked_from.is_some() => dt,
+        // Only a clone is droppable, and a clone is terminal by construction: a kept data table is
+        // a pointer at the parent's database, which this fork does not own.
+        let database = match datatables.get(dt_name) {
+            Some(dt) if dt.forked_from.is_some() => match dt.database.as_ref() {
+                Some(database) => database,
+                None => continue,
+            },
             _ => continue,
         };
 
-        if dt.database.resource_type
-            == windmill_common::workspaces::DataTableCatalogResourceType::Instance
-        {
-            let db_to_drop = &dt.database.resource_path;
+        if database.resource_type.is_windmill_managed() {
+            let db_to_drop = &database.resource_path;
             if !db_to_drop.starts_with("wm_fork_") {
                 errors.push(format!(
                     "Refusing to drop instance database '{}' for datatable://{}:  name does not start with 'wm_fork_'",
@@ -1359,7 +1433,42 @@ pub async fn drop_forked_datatable_databases(
                 ));
                 continue;
             }
-            if let Err(e) = windmill_common::drop_custom_instance_database(&db, db_to_drop).await {
+            // The fork's own entry is what is going away; anything else still reaching the copy,
+            // a child fork's pointer at this entry included, keeps it. The lock keeps a child fork
+            // from gaining such a pointer before the drop.
+            let dropped = async {
+                let mut tx = db.begin().await?;
+                windmill_common::workspaces::lock_fork_datatables(&mut tx, &w_id).await?;
+                if database.resource_type
+                    == windmill_common::workspaces::DataTableCatalogResourceType::ExternalInstance
+                {
+                    windmill_common::external_instance_pg::drop_external_instance_database_unchecked(
+                        &db,
+                        db_to_drop,
+                        Some((&w_id, dt_name)),
+                    )
+                    .await?;
+                } else {
+                    let uses = windmill_common::workspaces::managed_database_uses(
+                        &mut tx,
+                        windmill_common::workspaces::DataTableCatalogResourceType::Instance,
+                        db_to_drop,
+                        Some((&w_id, dt_name)),
+                    )
+                    .await?;
+                    if !uses.is_empty() {
+                        return Err(Error::BadRequest(format!(
+                            "it is still used by {}",
+                            uses.join(", ")
+                        )));
+                    }
+                    windmill_common::drop_custom_instance_database(&db, db_to_drop).await?;
+                }
+                tx.commit().await?;
+                Ok::<_, Error>(())
+            }
+            .await;
+            if let Err(e) = dropped {
                 errors.push(format!(
                     "Could not drop instance database '{}' for datatable://{}: {}",
                     db_to_drop, dt_name, e
@@ -1726,7 +1835,17 @@ async fn resolve_fork_catalog_pg(
             "ducklake://{ducklake_name}: malformed registry catalog identity `{catalog}`"
         ))
     })?;
-    let catalog_resource = if resource_type == "instance" {
+    let catalog_resource = if resource_type == "external_instance" {
+        serde_json::to_value(
+            windmill_common::external_instance_pg::external_instance_connection_unchecked(
+                db,
+                resource_path,
+                false,
+            )
+            .await?,
+        )
+        .map_err(|e| Error::internal_err(format!("serializing pg creds: {e}")))?
+    } else if resource_type == "instance" {
         let mut pg_creds = windmill_common::PgDatabase::parse_uri(
             &windmill_common::get_database_url().await?.as_str().await,
         )?;

backend/windmill-api/openapi.yaml

@@ -1572,6 +1572,104 @@ paths:
               schema:
                 type: object
 
+  /settings/external_instance_pg/status:
+    get:
+      summary: Returns whether the external instance cluster is configured and how its last setup went
+      operationId: getExternalInstancePgStatus
+      tags:
+        - setting
+      responses:
+        "200":
+          description: external instance cluster status
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ExternalInstancePgStatus"
+
+  /settings/external_instance_pg/setup:
+    post:
+      summary: Sets up the external instance cluster with its saved admin login, optionally rotating the passwords Windmill manages on it (enterprise edition only)
+      operationId: setupExternalInstancePg
+      tags:
+        - setting
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                rotate_passwords:
+                  type: boolean
+      responses:
+        "200":
+          description: the setup report, also stored as the last setup
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ExternalInstancePgSetupReport"
+
+  /settings/external_instance_pg/databases:
+    get:
+      summary: Lists the databases Windmill created on the external instance cluster, with the workspaces whose data tables, Ducklake catalogs or pending fork cleanups use each
+      operationId: listExternalInstancePgDatabases
+      tags:
+        - setting
+      responses:
+        "200":
+          description: databases by name
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties:
+                  $ref: "#/components/schemas/CustomInstanceDb"
+
+  /settings/external_instance_pg/databases/{name}:
+    post:
+      summary: Creates a database on the external instance cluster (enterprise edition only)
+      operationId: createExternalInstancePgDatabase
+      tags:
+        - setting
+      parameters:
+        - name: name
+          in: path
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                tag:
+                  $ref: "#/components/schemas/CustomInstanceDbTag"
+      responses:
+        "200":
+          description: database created
+          content:
+            application/json:
+              schema: {}
+    delete:
+      summary: Drops a database Windmill created on the external instance cluster, refused while a data table, Ducklake catalog or pending fork cleanup uses it
+      operationId: dropExternalInstancePgDatabase
+      tags:
+        - setting
+      parameters:
+        - name: name
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: database dropped
+          content:
+            application/json:
+              schema: {}
+
   /settings/list_custom_instance_pg_databases:
     post:
       summary: Returns the set-up statuses of custom instance pg databases
@@ -1588,6 +1686,97 @@ paths:
                 additionalProperties:
                   $ref: "#/components/schemas/CustomInstanceDb"
 
+  /settings/datatable_roles:
+    get:
+      summary: list the data table roles of one Windmill-managed Postgres cluster
+      operationId: listInstanceDatatableRoles
+      tags:
+        - setting
+      parameters:
+        - in: query
+          name: cluster
+          required: false
+          schema:
+            $ref: "#/components/schemas/DatatableRoleCluster"
+      responses:
+        "200":
+          description: the cluster's role catalog
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/InstanceDatatableRole"
+    post:
+      summary: create a data table role on a Windmill-managed Postgres cluster
+      operationId: createInstanceDatatableRole
+      tags:
+        - setting
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [name]
+              properties:
+                name:
+                  type: string
+                cluster:
+                  $ref: "#/components/schemas/DatatableRoleCluster"
+      responses:
+        "200":
+          description: the created role
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/InstanceDatatableRole"
+
+  /settings/datatable_roles/{id}:
+    post:
+      summary: rename a data table role or turn its login on and off
+      operationId: updateInstanceDatatableRole
+      tags:
+        - setting
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                name:
+                  type: string
+                enabled:
+                  type: boolean
+      responses:
+        "200":
+          description: the updated role
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/InstanceDatatableRole"
+    delete:
+      summary: drop a data table role from the cluster and from every workspace that named it
+      operationId: deleteInstanceDatatableRole
+      tags:
+        - setting
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: deleted
+
   /settings/setup_custom_instance_pg_database/{name}:
     post:
       summary: Runs CREATE DATABASE on the Windmill Postgres and grants access to the custom_instance_user
@@ -5141,15 +5330,197 @@ paths:
                 type: array
                 items:
                   type: object
-                  required: [name, resource_type, resource_path]
+                  required: [name, resource_type, resource_path, permissioned]
                   properties:
                     name:
                       type: string
                     resource_type:
                       type: string
-                      enum: [postgres, instance]
+                      enum: [postgres, instance, external_instance]
                     resource_path:
                       type: string
+                    governing_workspace_id:
+                      type: string
+                    permissioned:
+                      type: boolean
+
+  /w/{workspace}/workspaces/datatable_permissions/{datatable_name}:
+    get:
+      summary: get who may connect to a data table as which role
+      operationId: getDatatablePermissions
+      tags:
+        - workspace
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: datatable_name
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: the data table's roles and their tenants
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DatatablePermissions"
+    post:
+      summary: set who may connect to a data table as which role
+      operationId: setDatatablePermissions
+      tags:
+        - workspace
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: datatable_name
+          in: path
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [permissioned]
+              properties:
+                permissioned:
+                  type: boolean
+                default_role:
+                  type: string
+                roles:
+                  type: array
+                  items:
+                    $ref: "#/components/schemas/DatatableRoleTenants"
+      responses:
+        "200":
+          description: status
+          content:
+            text/plain:
+              schema:
+                type: string
+
+  /w/{workspace}/workspaces/datatable_acl/{datatable_name}:
+    get:
+      summary: read the owner and grants of an instance data table's database, schema or table
+      operationId: getDatatableAcl
+      tags:
+        - workspace
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: datatable_name
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: kind
+          in: query
+          required: true
+          schema:
+            type: string
+            enum: [database, schema, table]
+        - name: schema
+          in: query
+          required: false
+          schema:
+            type: string
+        - name: table
+          in: query
+          required: false
+          schema:
+            type: string
+      responses:
+        "200":
+          description: owner and grants
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DatatableAclInfo"
+
+  /w/{workspace}/workspaces/datatable_acl/{datatable_name}/plan:
+    post:
+      summary: preview the SQL an ownership or grant change would run (data table administrators only)
+      operationId: planDatatableAcl
+      tags:
+        - workspace
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: datatable_name
+          in: path
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AclChangeRequest"
+      responses:
+        "200":
+          description: statements that would run, in a single transaction
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AclPlan"
+
+  /w/{workspace}/workspaces/datatable_acl/{datatable_name}/apply:
+    post:
+      summary: run an ownership or grant change exactly as planned (data table administrators only)
+      operationId: applyDatatableAcl
+      tags:
+        - workspace
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: datatable_name
+          in: path
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AclChangeRequest"
+      responses:
+        "200":
+          description: change applied
+          content:
+            text/plain:
+              schema:
+                type: string
+
+  /w/{workspace}/workspaces/datatable_usable_roles/{datatable_name}:
+    get:
+      summary: list the data table roles the caller may connect as
+      operationId: listUsableDatatableRoles
+      tags:
+        - workspace
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: datatable_name
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: usable roles
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [permissioned, roles, default_role]
+                properties:
+                  permissioned:
+                    type: boolean
+                  roles:
+                    type: array
+                    items:
+                      type: string
+                  default_role:
+                    type: string
 
   /w/{workspace}/workspaces/list_datatable_schemas:
     get:
@@ -5223,6 +5594,21 @@ paths:
         - workspace
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
+        - name: datatable_name
+          in: query
+          description: list only this data table; each listed data table opens a connection to its database
+          schema:
+            type: string
+        - name: role_for
+          in: query
+          description: the data table `role` applies to; every other one is listed as its default role
+          schema:
+            type: string
+        - name: role
+          in: query
+          description: the role to list `role_for` as; refused, in that entry's `error`, if the caller may not use it
+          schema:
+            type: string
       responses:
         "200":
           description: table metadata of all datatables
@@ -5256,6 +5642,11 @@ paths:
           required: true
           schema:
             type: string
+        - name: role
+          in: query
+          description: the data table role to read the table as; defaults to the data table's default role
+          schema:
+            type: string
       responses:
         "200":
           description: schema of one datatable table
@@ -5331,7 +5722,22 @@ paths:
           description: status
           content:
             application/json:
-              schema: {}
+              schema:
+                type: object
+                properties:
+                  stranded_references:
+                    description: >-
+                      Data tables in other workspaces that were governed by one this save deleted
+                      and no longer resolve.
+                    type: array
+                    items:
+                      type: object
+                      required: [workspace_id, datatable]
+                      properties:
+                        workspace_id:
+                          type: string
+                        datatable:
+                          type: string
 
   /w/{workspace}/workspaces/run_datatable_migrations/{datatable_name}:
     post:
@@ -33321,6 +33727,365 @@ components:
         - ducklake
         - datatable
 
+    ExternalInstancePgSetupStep:
+      type: object
+      required: [name, status, message]
+      properties:
+        name:
+          type: string
+        status:
+          type: string
+          enum: [ok, warning, error]
+        message:
+          type: string
+
+    ExternalInstancePgSetupReport:
+      type: object
+      required: [success, finished_at, steps]
+      properties:
+        success:
+          type: boolean
+          description: no step failed; warnings leave it true
+        finished_at:
+          type: string
+          format: date-time
+        steps:
+          type: array
+          items:
+            $ref: "#/components/schemas/ExternalInstancePgSetupStep"
+
+    ExternalInstancePgStatus:
+      type: object
+      required: [configured, database_count]
+      properties:
+        configured:
+          type: boolean
+        database_count:
+          type: integer
+        last_setup:
+          $ref: "#/components/schemas/ExternalInstancePgSetupReport"
+
+    DatatableRoleCluster:
+      type: string
+      description: >-
+        The Windmill-managed Postgres cluster a data table role is a login on: Windmill's own
+        (behind `instance` data tables) or the external instance cluster (behind
+        `external_instance` ones). Defaults to `instance`.
+      enum: [instance, external_instance]
+
+    InstanceDatatableRole:
+      type: object
+      required: [id, name, enabled, cluster]
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        enabled:
+          type: boolean
+        cluster:
+          $ref: "#/components/schemas/DatatableRoleCluster"
+
+    DatatableRoleTenants:
+      type: object
+      required: [id, tenants]
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        tenants:
+          type: array
+          items:
+            type: string
+
+    DatatablePermissions:
+      type: object
+      required: [supported, permissioned, default_role, roles, editable, available_roles]
+      properties:
+        supported:
+          type: boolean
+          description: >-
+            Whether this data table can be put under roles at all. Only one on a database Windmill
+            manages can: a role is a login on that database's cluster.
+        cluster:
+          $ref: "#/components/schemas/DatatableRoleCluster"
+        permissioned:
+          type: boolean
+        default_role:
+          type: string
+        roles:
+          type: array
+          items:
+            $ref: "#/components/schemas/DatatableRoleTenants"
+        governing_workspace_id:
+          type: string
+        editable:
+          type: boolean
+        available_roles:
+          type: array
+          items:
+            $ref: "#/components/schemas/InstanceDatatableRole"
+        ungoverned_reachers:
+          type: array
+          items:
+            type: object
+            required: [workspace_id, datatable]
+            properties:
+              workspace_id:
+                type: string
+              datatable:
+                type: string
+
+    AclTarget:
+      description: what access is read or changed on
+      oneOf:
+        - $ref: "#/components/schemas/AclTargetDatabase"
+        - $ref: "#/components/schemas/AclTargetSchema"
+        - $ref: "#/components/schemas/AclTargetTable"
+      discriminator:
+        propertyName: kind
+        mapping:
+          database: "#/components/schemas/AclTargetDatabase"
+          schema: "#/components/schemas/AclTargetSchema"
+          table: "#/components/schemas/AclTargetTable"
+
+    AclTargetDatabase:
+      type: object
+      required: [kind]
+      properties:
+        kind:
+          type: string
+          enum: [database]
+
+    AclTargetSchema:
+      type: object
+      required: [kind, schema]
+      properties:
+        kind:
+          type: string
+          enum: [schema]
+        schema:
+          type: string
+
+    AclTargetTable:
+      type: object
+      required: [kind, schema, table]
+      properties:
+        kind:
+          type: string
+          enum: [table]
+        schema:
+          type: string
+        table:
+          type: string
+
+    AclChange:
+      description: one change to plan or apply
+      oneOf:
+        - $ref: "#/components/schemas/AclChangeSetOwner"
+        - $ref: "#/components/schemas/AclChangeGrant"
+        - $ref: "#/components/schemas/AclChangeRevoke"
+      discriminator:
+        propertyName: type
+        mapping:
+          set_owner: "#/components/schemas/AclChangeSetOwner"
+          grant: "#/components/schemas/AclChangeGrant"
+          revoke: "#/components/schemas/AclChangeRevoke"
+
+    AclChangeSetOwner:
+      type: object
+      description: >-
+        hands the target to role — for a schema, with everything already in it but an extension's
+        members, which stay with the extension
+      required: [type, role]
+      properties:
+        type:
+          type: string
+          enum: [set_owner]
+        role:
+          type: string
+          description: a data table role of the instance, or admin
+
+    AclChangeGrant:
+      type: object
+      required: [type, role, privileges, scope]
+      properties:
+        type:
+          type: string
+          enum: [grant]
+        role:
+          type: string
+          description: a data table role of the instance, or admin
+        privileges:
+          type: array
+          items:
+            type: string
+        scope:
+          $ref: "#/components/schemas/AclGrantScope"
+
+    AclChangeRevoke:
+      type: object
+      required: [type, role, privileges, scope]
+      properties:
+        type:
+          type: string
+          enum: [revoke]
+        role:
+          type: string
+          description: a data table role of the instance, other than admin
+        privileges:
+          type: array
+          items:
+            type: string
+        scope:
+          $ref: "#/components/schemas/AclGrantScope"
+        objects:
+          type: array
+          description: >-
+            objects inside the target the revoke covers, empty for the target itself. Only with the
+            target scope; a revoke on all objects of a kind is refused, since it cannot say which
+            grants it takes back.
+          items:
+            $ref: "#/components/schemas/AclObject"
+
+    AclGrantScope:
+      type: string
+      enum:
+        [
+          target,
+          all_tables,
+          all_sequences,
+          all_functions,
+          future_tables,
+          future_sequences,
+          future_functions,
+        ]
+
+    AclChangeRequest:
+      type: object
+      required: [target, change]
+      properties:
+        target:
+          $ref: "#/components/schemas/AclTarget"
+        change:
+          $ref: "#/components/schemas/AclChange"
+        statements:
+          type: array
+          description: >-
+            The statements the plan showed. Required to apply, which plans again and refuses if
+            the result differs.
+          items:
+            type: string
+
+    AclPlan:
+      type: object
+      required: [statements, warnings]
+      properties:
+        statements:
+          type: array
+          items:
+            type: string
+        warnings:
+          type: array
+          items:
+            type: string
+
+    AclObject:
+      type: object
+      required: [name, kind]
+      properties:
+        name:
+          type: string
+        kind:
+          type: string
+          description: >-
+            TABLE, SEQUENCE, FUNCTION, PROCEDURE or TYPE — what the object is. A revoke turns it
+            into the keyword it takes, ROUTINE for both routine kinds; a type's grants are read
+            only.
+        args:
+          type: string
+          description: identity arguments of a routine, which is what tells two of the same name apart
+
+    AclGrant:
+      type: object
+      required: [grantee, privileges, sources]
+      properties:
+        grantee:
+          type: string
+        privileges:
+          type: array
+          items:
+            type: string
+        object:
+          $ref: "#/components/schemas/AclObject"
+        future:
+          type: string
+          description: >-
+            set for a default privilege, naming the kind of object it covers (TABLES, SEQUENCES,
+            FUNCTIONS, TYPES, or SCHEMAS). On a schema, the defaults set in that schema; on the
+            database, the ones set database-wide, which apply in every schema and which no schema's
+            own defaults take back.
+        sources:
+          type: array
+          description: >-
+            the roles the grant comes from, each once — who granted it, or for a default privilege
+            the role whose future objects it covers. A revoke of some of the grant's privileges
+            takes them back from every source that gave them.
+          items:
+            $ref: "#/components/schemas/AclSource"
+
+    AclSource:
+      type: object
+      required: [role, privileges, reachable]
+      properties:
+        role:
+          type: string
+        privileges:
+          type: array
+          description: >-
+            what role gave of the grant's privileges. A revoke is held back only by a source out of
+            reach that gave some of what it takes back.
+          items:
+            type: string
+        reachable:
+          type: boolean
+          description: >-
+            whether the data table's connection can take back what role gave. On an object that is
+            the owner, when the connection acts for the owner, and otherwise the connection itself;
+            for a default privilege, a creating role the connection acts for. What a source out of
+            reach gave is not revocable from here; privileges only other sources gave still are.
+
+    DatatableAclInfo:
+      type: object
+      required: [owner, roles, editable, supports_maintain, dbname, grants, children]
+      properties:
+        owner:
+          type: string
+        roles:
+          type: array
+          description: the roles a change may name; empty unless the caller may change anything
+          items:
+            type: string
+        editable:
+          type: boolean
+          description: whether the caller may plan and apply changes
+        supports_maintain:
+          type: boolean
+          description: whether the server is Postgres 17+, which added the MAINTAIN table privilege
+        dbname:
+          type: string
+          description: the database the target lives in
+        grants:
+          type: array
+          items:
+            $ref: "#/components/schemas/AclGrant"
+        children:
+          type: array
+          description: a database's schemas, or a schema's tables
+          items:
+            type: string
+
     CustomInstanceDb:
       type: object
       required:
@@ -33345,6 +34110,9 @@ components:
           items:
             type: string
           description: Workspaces that reference this database via a ducklake catalog or datatable database with resource_type 'instance'. Computed at request time, not persisted.
+        workspace_id:
+          type: string
+          description: The workspace a member created this database for as a fork copy. Only that workspace can import into it or point a fork at it.
 
     NewSqsTrigger:
       type: object
@@ -35318,6 +36086,7 @@ components:
                       - postgresql
                       - mysql
                       - instance
+                      - external_instance
                   resource_path:
                     type: string
                 required:
@@ -35369,9 +36138,11 @@ components:
           type: object
           additionalProperties:
             type: object
-            required: [database]
             properties:
               database:
+                description: >-
+                  Set on an entry that owns its database. Absent on a fork's entry, which points at
+                  another workspace's data table instead.
                 type: object
                 properties:
                   resource_type:
@@ -35379,10 +36150,22 @@ components:
                     enum:
                       - postgresql
                       - instance
+                      - external_instance
                   resource_path:
                     type: string
                 required:
                   - resource_type
+              reference:
+                description: >-
+                  The workspace and data table that govern this one. Server-owned: written by fork
+                  creation, and carried across a settings save whatever the request says.
+                type: object
+                required: [workspace_id, datatable]
+                properties:
+                  workspace_id:
+                    type: string
+                  datatable:
+                    type: string
               migrations_enabled:
                 type: boolean
                 description: Whether the SQL migrations feature is opted in for this data table
@@ -35451,7 +36234,17 @@ components:
 
     DataTableTables:
       type: object
-      required: [datatable_name, schemas]
+      required:
+        [
+          datatable_name,
+          schemas,
+          instance,
+          permissioned,
+          usable_roles,
+          default_role,
+          can_create_schema,
+          creatable_schemas,
+        ]
       properties:
         datatable_name:
           type: string
@@ -35464,6 +36257,26 @@ components:
               type: string
         error:
           type: string
+        instance:
+          type: boolean
+          description: on the instance database, the only kind that can be under roles or have its access edited
+        permissioned:
+          type: boolean
+        usable_roles:
+          type: array
+          description: the roles the caller may connect as, by name; empty when not under roles
+          items:
+            type: string
+        default_role:
+          type: string
+        can_create_schema:
+          type: boolean
+          description: whether the role the listing connected as may create schemas
+        creatable_schemas:
+          type: array
+          description: the schemas the role the listing connected as may create in
+          items:
+            type: string
 
     DataTableTableSchema:
       type: object

backend/windmill-api/src/capture.rs

@@ -567,6 +567,9 @@ async fn set_config(
     };
 
     let mut tx = user_db.begin(&authed).await?;
+    if matches!(nc.trigger_kind, TriggerKind::Postgres) {
+        windmill_common::datatable_roles::lock_datatable_streams(&mut *tx, false).await?;
+    }
 
     sqlx::query!(
         r#"
@@ -614,6 +617,9 @@ async fn ping_config(
     )>,
 ) -> Result<()> {
     let mut tx = user_db.begin(&authed).await?;
+    if matches!(trigger_kind, TriggerKind::Postgres) {
+        windmill_common::datatable_roles::lock_datatable_streams(&mut *tx, false).await?;
+    }
 
     sqlx::query!(
         r#"

backend/windmill-api/src/jobs.rs

@@ -8343,8 +8343,9 @@ pub async fn run_wait_result_flow_by_version(
 /// job lives, in particular DuckDB, which runs in-process in the worker.
 ///
 /// What it does permit is any statement against the workspace's data tables, writes and DDL
-/// included: the helper's body is an unrestricted SQL template and data tables carry no
-/// per-user ACL. Narrowing that is a separate decision from this exemption.
+/// included: the helper's body is an unrestricted SQL template. What that reaches is the
+/// operator's own data table role — the preview job is permissioned as them, so the executor
+/// resolves it under their tenancy like any other job.
 ///
 /// The database argument is only half the target: the executor honors a `-- database`
 /// directive in the SQL over it, and `-- s3` redirects the result set, so both are refused.
@@ -8576,7 +8577,7 @@ async fn run_inline_preview_script(
 #[cfg(not(feature = "run_inline"))]
 async fn run_inline_preview_script() -> error::Result<Response> {
     Err(error::Error::InternalErr(
-        "inline preview requires the worker feature".to_string(),
+        "inline preview requires the run_inline feature on the worker".to_string(),
     ))
 }
 
@@ -8700,7 +8701,12 @@ fn register_potential_assets_on_inline_execution(
             .as_ref()
             .and_then(|args| args.get("database"))
             .map(|v| v.get().trim_matches('"'))
-            .and_then(|dt| dt.strip_prefix("datatable://"));
+            .and_then(|dt| dt.strip_prefix("datatable://"))
+            // `?role=` picks the connection, not the data table. Anything else after a `?` may be
+            // part of a name stored before names were restricted, so it stays.
+            .map(|dt| {
+                windmill_common::workspaces::parse_datatable_ref(dt).map_or(dt, |(name, _)| name)
+            });
         if let Some(datatable) = datatable {
             let re = regex::Regex::new(r#"SET search_path TO "([^"]+)";"#).unwrap();
             let (schema, content) = if let Some(captures) = re.captures(&preview.content) {

backend/windmill-api/src/users.rs

@@ -352,6 +352,17 @@ async fn update_username_in_workpsace<'c>(
     new_username: &str,
     w_id: &str,
 ) -> error::Result<()> {
+    // ---- data table tenants ----
+    // Tenants name the user, so the rename has to follow here too; a list left naming the old
+    // username silently drops the access instead of moving it.
+    windmill_common::workspaces::rename_datatable_tenant_in_workspace(
+        tx,
+        w_id,
+        &format!("u/{old_username}"),
+        &format!("u/{new_username}"),
+    )
+    .await?;
+
     // ---- instance and workspace users ----
     sqlx::query!(
         "UPDATE usr SET username = $1 WHERE email = $2",

backend/windmill-api/src/workspaces_export.rs

@@ -1639,7 +1639,7 @@ pub(crate) async fn tarball_workspace(
                 mute_critical_alerts: row.mute_critical_alerts,
                 color: row.color.clone(),
                 operator_settings: row.operator_settings.clone(),
-                datatable: row.datatable.clone(),
+                datatable: windmill_common::workspaces::strip_datatable_permissions(row.datatable.clone()),
                 slack_team_id: row.slack_team_id.clone(),
                 slack_name: row.slack_name.clone(),
                 slack_command_script: row.slack_command_script.clone(),
@@ -1703,7 +1703,7 @@ pub(crate) async fn tarball_workspace(
                 mute_critical_alerts: row.mute_critical_alerts,
                 color: row.color,
                 operator_settings: row.operator_settings,
-                datatable: row.datatable,
+                datatable: windmill_common::workspaces::strip_datatable_permissions(row.datatable),
                 slack_team_id: row.slack_team_id,
                 slack_name: row.slack_name,
                 slack_command_script: row.slack_command_script,

backend/windmill-common/Cargo.toml

@@ -75,6 +75,7 @@ bitflags.workspace = true
 once_cell.workspace = true
 phf.workspace = true
 tokio-postgres.workspace = true
+postgres-protocol.workspace = true
 postgres-native-tls.workspace = true
 native-tls.workspace = true
 

backend/windmill-common/src/datatable_roles.rs

@@ -0,0 +1,445 @@
+/*
+ * Author: Ruben Fiszel
+ * Copyright: Windmill Labs, Inc 2022
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the included NOTICE for copyright information and
+ * LICENSE-AGPL for a copy of the license.
+ */
+
+//! The instance's data table role catalogs.
+//!
+//! A data table role is a real Postgres login role on one cluster — Windmill's own, or the external
+//! instance cluster — named exactly as the user named it, shared by every database Windmill manages
+//! on that cluster. Each cluster has its own catalog: a role exists where it was created and nowhere
+//! else. Windmill decides who may ask for a role (the per-data-table tenant lists in
+//! [`crate::workspaces`]); Postgres decides what the role may then touch. The catalog here is only
+//! the first half's vocabulary plus the cluster provisioning.
+//!
+//! Entries are keyed by a generated id so a rename moves nothing else: tenants name the id.
+
+use std::collections::BTreeMap;
+
+use serde::{Deserialize, Serialize};
+
+use crate::{
+    error::{Error, Result},
+    workspaces::DataTableCatalogResourceType,
+    DB,
+};
+
+/// The cluster a role catalog belongs to.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum DatatableRoleCluster {
+    /// Windmill's own Postgres, behind `instance` data tables.
+    #[default]
+    Instance,
+    /// The external instance cluster, behind `external_instance` data tables.
+    ExternalInstance,
+}
+
+impl DatatableRoleCluster {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Instance => "instance",
+            Self::ExternalInstance => "external_instance",
+        }
+    }
+
+    pub fn parse(value: &str) -> Result<Self> {
+        match value {
+            "instance" => Ok(Self::Instance),
+            "external_instance" => Ok(Self::ExternalInstance),
+            other => Err(Error::BadRequest(format!(
+                "Unknown data table role cluster '{other}': expected instance or external_instance"
+            ))),
+        }
+    }
+
+    /// The cluster whose roles a data table on `kind` can use. `None` for a resource-backed one,
+    /// which is never under roles.
+    pub fn of(kind: DataTableCatalogResourceType) -> Option<Self> {
+        match kind {
+            DataTableCatalogResourceType::Instance => Some(Self::Instance),
+            DataTableCatalogResourceType::ExternalInstance => Some(Self::ExternalInstance),
+            DataTableCatalogResourceType::Postgresql => None,
+        }
+    }
+}
+
+/// The connection every data table resolved to before roles existed (`custom_instance_user`). It
+/// owns every pre-existing object, so it is a reserved name rather than a catalog entry: never
+/// created, renamed or dropped.
+pub const ADMIN_DATATABLE_ROLE: &str = "admin";
+
+/// The login the admin connection uses, and the role every created role is granted to — that
+/// membership is what later lets it `ALTER ... OWNER TO` a role and drop it.
+pub const CUSTOM_INSTANCE_USER: &str = "custom_instance_user";
+
+/// One catalog entry, as stored in `datatable_role`. The password is per role and instance-wide;
+/// it belongs to the instance, not to any workspace's settings.
+/// No `Serialize`/`Deserialize`: the catalog is rows now, and a derived `Serialize` would emit
+/// `pwd` — the same way out for a credential that the hand-written `Debug` below closes on the log
+/// side.
+#[derive(Clone)]
+pub struct InstanceDatatableRole {
+    /// The Postgres role name, verbatim.
+    pub name: String,
+    pub enabled: bool,
+    /// Absent only for a role whose provisioning did not finish; resolving as it then errors
+    /// rather than falling back to admin.
+    ///
+    /// A plain string rather than a `StringOrSecretRef` like the instance user's password: that
+    /// one is a secret ref because an operator supplies it and may want it to come from their own
+    /// backend, while this one is minted here and never entered by anyone, so there is nothing for
+    /// a ref to point at. Encrypting generated secrets at rest is a separate change that would
+    /// take the replication password with it.
+    pub pwd: Option<String>,
+}
+
+/// Hand-written so `{:?}` on a catalog cannot put a live Postgres password in a log line or an
+/// audit record. Everything else about the entry is safe to print.
+impl std::fmt::Debug for InstanceDatatableRole {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("InstanceDatatableRole")
+            .field("name", &self.name)
+            .field("enabled", &self.enabled)
+            .field("pwd", &self.pwd.as_ref().map(|_| "<redacted>"))
+            .finish()
+    }
+}
+
+pub type DatatableRoleCatalog = BTreeMap<String, InstanceDatatableRole>;
+
+/// Names Postgres or Windmill already owns. `admin` is excluded because it never reaches the
+/// cluster as a role name at all — it resolves to `custom_instance_user`.
+fn is_reserved_role_name(name: &str) -> bool {
+    let lower = name.to_ascii_lowercase();
+    lower == ADMIN_DATATABLE_ROLE
+        || lower == "postgres"
+        || lower == "public"
+        || lower.starts_with("pg_")
+        || lower.starts_with("windmill_")
+        || lower.starts_with("custom_instance_")
+}
+
+/// The charset is what makes every downstream interpolation safe: the name reaches Postgres as a
+/// quoted identifier, a `-- role <name>` annotation, and a `?role=` query parameter.
+pub fn validate_role_name(name: &str) -> Result<()> {
+    if name.is_empty() || name.len() > 63 {
+        return Err(Error::BadRequest(format!(
+            "Invalid data table role name '{name}': it must be between 1 and 63 characters"
+        )));
+    }
+    if !name
+        .chars()
+        .all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '-')
+    {
+        return Err(Error::BadRequest(format!(
+            "Invalid data table role name '{name}': only letters, digits, '_' and '-' are allowed"
+        )));
+    }
+    if is_reserved_role_name(name) {
+        return Err(Error::BadRequest(format!(
+            "'{name}' is reserved and cannot be used as a data table role name"
+        )));
+    }
+    Ok(())
+}
+
+/// A double-quoted Postgres identifier. Doubling `"` is Postgres's own escaping inside one, so this
+/// quotes any name — schema, table or role. Role names are validated as well
+/// ([`validate_role_name`]) because they also travel unquoted, in `-- role <name>` and `?role=`.
+pub fn quote_ident(name: &str) -> String {
+    format!("\"{}\"", name.replace('"', "\"\""))
+}
+
+/// Serialize the mutations that are not already serialized by the row itself.
+///
+/// A create is an insert and a delete is a delete, which Postgres orders for us — the unique index
+/// on `name` is what makes two concurrent creates of the same name one winner and one error. What
+/// still needs it is the window between the cluster DDL and the row: `CREATE ROLE` is not visible
+/// to another transaction's `pg_roles` check until commit, so without this two creates of the same
+/// name both pass their existence check and one fails on the index having already made the login.
+/// Held for the transaction, so the DDL has to run on that same transaction to be covered.
+pub async fn lock_role_catalog(tx: &mut sqlx::Transaction<'_, sqlx::Postgres>) -> Result<()> {
+    sqlx::query!("SELECT pg_advisory_xact_lock(hashtext('datatable_role_catalog'))")
+        .execute(&mut **tx)
+        .await?;
+    Ok(())
+}
+
+/// A replication stream reads every row whatever a data table's roles grant. Turning roles on looks
+/// for streams holding this exclusive; whatever can start a Postgres trigger or capture streaming
+/// holds it shared on the transaction that commits it. So either the look sees the stream, or the
+/// stream's listener connects after roles are committed and refuses. Held for the transaction.
+pub async fn lock_datatable_streams(conn: &mut sqlx::PgConnection, exclusive: bool) -> Result<()> {
+    let lock = if exclusive {
+        "pg_advisory_xact_lock"
+    } else {
+        "pg_advisory_xact_lock_shared"
+    };
+    sqlx::query(&format!("SELECT {lock}(hashtext('datatable_streams'))"))
+        .execute(conn)
+        .await?;
+    Ok(())
+}
+
+/// Whether an instance database is reached only through entries under roles is decided by two
+/// writes that lock different workspaces' settings rows: turning roles on for one entry, and a
+/// settings save pointing an entry without roles at the database. Each holds this for every
+/// database it decides on, so neither reads past the other's uncommitted write. Held for the
+/// transaction; the names are locked in sorted order so two holders cannot deadlock.
+pub async fn lock_instance_databases_governance<'a>(
+    conn: &mut sqlx::PgConnection,
+    dbnames: impl IntoIterator<Item = &'a str>,
+) -> Result<()> {
+    let dbnames: std::collections::BTreeSet<&str> = dbnames.into_iter().collect();
+    for dbname in dbnames {
+        sqlx::query("SELECT pg_advisory_xact_lock(hashtext('datatable_instance_database:' || $1))")
+            .bind(dbname)
+            .execute(&mut *conn)
+            .await?;
+    }
+    Ok(())
+}
+
+/// Disclosure: returns every role's stored Postgres password in plaintext. Any server path that
+/// has to resolve or name a role may call it — including handlers open to a workspace member, who
+/// need the names — but callers MUST NOT let `pwd` reach a response, a log line, an audit record
+/// or an export. Nothing about who may call it: the credential is the whole risk, and `Debug` is
+/// hand-written to redact it for the same reason.
+pub async fn read_role_catalog(
+    db: &DB,
+    cluster: DatatableRoleCluster,
+) -> Result<DatatableRoleCatalog> {
+    crate::datatable_roles_oss::read_role_catalog(db, cluster).await
+}
+
+/// As [`read_role_catalog`], reading inside the caller's transaction so the value is the one
+/// [`lock_role_catalog`] is protecting. Same disclosure contract.
+pub async fn read_role_catalog_tx(
+    tx: &mut sqlx::Transaction<'_, sqlx::Postgres>,
+    cluster: DatatableRoleCluster,
+) -> Result<DatatableRoleCatalog> {
+    crate::datatable_roles_oss::read_role_catalog_tx(tx, cluster).await
+}
+
+/// The cluster a role belongs to, or `None` if no role has this id.
+pub async fn role_cluster(
+    tx: &mut sqlx::Transaction<'_, sqlx::Postgres>,
+    id: &str,
+) -> Result<Option<DatatableRoleCluster>> {
+    crate::datatable_roles_oss::role_cluster(tx, id).await
+}
+
+/// Record a role, in the caller's transaction. On Windmill's own cluster that commits it with the
+/// `CREATE ROLE` it describes; on the external cluster the role already exists by then.
+///
+/// Authorization: writes a generated Postgres credential. Callers MUST restrict this to superadmin
+/// paths and MUST hold [`lock_role_catalog`] on `tx`.
+pub async fn insert_role_catalog_entry(
+    tx: &mut sqlx::Transaction<'_, sqlx::Postgres>,
+    id: &str,
+    cluster: DatatableRoleCluster,
+    role: &InstanceDatatableRole,
+) -> Result<()> {
+    crate::datatable_roles_oss::insert_role_catalog_entry(tx, id, cluster, role).await
+}
+
+/// Update a role's recorded name, login flag and password. Same contract as
+/// [`insert_role_catalog_entry`].
+pub async fn update_role_catalog_entry(
+    tx: &mut sqlx::Transaction<'_, sqlx::Postgres>,
+    id: &str,
+    role: &InstanceDatatableRole,
+) -> Result<()> {
+    crate::datatable_roles_oss::update_role_catalog_entry(tx, id, role).await
+}
+
+/// Forget a role. Same contract as [`insert_role_catalog_entry`]; run it in the transaction that
+/// drops the cluster login, so the two cannot disagree.
+pub async fn delete_role_catalog_entry(
+    tx: &mut sqlx::Transaction<'_, sqlx::Postgres>,
+    id: &str,
+) -> Result<()> {
+    crate::datatable_roles_oss::delete_role_catalog_entry(tx, id).await
+}
+
+/// Resolve the role a caller named to its catalog id. A disabled role is an error rather than a
+/// silent fallback: the caller asked for something the instance deliberately turned off.
+pub fn role_id_by_name<'a>(catalog: &'a DatatableRoleCatalog, name: &str) -> Result<&'a str> {
+    let entry = catalog
+        .iter()
+        .find(|(_, role)| role.name == name)
+        .ok_or_else(|| {
+            Error::NotFound(format!(
+                "'{name}' is not a data table role of this database's cluster. Defined roles: {}.",
+                catalog
+                    .values()
+                    .map(|r| r.name.as_str())
+                    .collect::<Vec<_>>()
+                    .join(", ")
+            ))
+        })?;
+    if !entry.1.enabled {
+        return Err(Error::BadRequest(format!(
+            "Data table role '{name}' is disabled on this instance"
+        )));
+    }
+    Ok(entry.0.as_str())
+}
+
+/// Every database Windmill manages on `cluster`. Role provisioning has to reach all of them: a role
+/// that cannot `CONNECT` to a database is refused by Postgres before any grant matters.
+///
+/// Authorization: checks nothing, and names every managed database across all workspaces. Callers
+/// MUST be superadmin-gated or keep the names server-side; never return them to a workspace caller.
+pub async fn registered_instance_databases(
+    db: &DB,
+    cluster: DatatableRoleCluster,
+) -> Result<Vec<String>> {
+    crate::datatable_roles_oss::registered_instance_databases(db, cluster).await
+}
+
+/// `CONNECT` on `dbname` for every enabled role of `cluster`, and none for `PUBLIC`. Run at role
+/// creation, at database creation, and lazily whenever a managed data table is administered, so a
+/// database provisioned before a role existed is repaired rather than left silently unreachable.
+///
+/// Authorization: rewrites a database's ACL with the server's own credentials and checks nothing.
+/// Callers MUST have authorized administration of `dbname` — superadmin, or an admin of the
+/// workspace governing a data table on it.
+pub async fn converge_connect_grants(
+    db: &DB,
+    cluster: DatatableRoleCluster,
+    dbname: &str,
+) -> Result<()> {
+    crate::datatable_roles_oss::converge_connect_grants(db, cluster, dbname).await
+}
+
+/// As [`converge_connect_grants`], with the catalog of `cluster` the caller already read. Same
+/// contract.
+pub async fn converge_connect_grants_with(
+    db: &DB,
+    cluster: DatatableRoleCluster,
+    dbname: &str,
+    catalog: &DatatableRoleCatalog,
+) -> Result<()> {
+    crate::datatable_roles_oss::converge_connect_grants_with(db, cluster, dbname, catalog).await
+}
+
+/// `CREATE ROLE <name> LOGIN PASSWORD ...; GRANT <name> TO custom_instance_user` on `cluster`. No
+/// privileges beyond that — an admin grants them through SQL or the ACL editor.
+///
+/// On Windmill's own cluster the DDL runs on `tx`, so it commits with the catalog row. The external
+/// cluster is another server: the role is created there before `tx` commits, and callers MUST drop
+/// it again ([`drop_datatable_role`]) if `tx` then fails to commit.
+///
+/// Authorization: creates a cluster-wide Postgres login. Callers MUST restrict this to superadmin
+/// paths, and MUST hold [`lock_role_catalog`] on `tx`.
+pub async fn create_datatable_role(
+    db: &DB,
+    tx: &mut sqlx::Transaction<'_, sqlx::Postgres>,
+    cluster: DatatableRoleCluster,
+    name: &str,
+    password: &str,
+) -> Result<()> {
+    crate::datatable_roles_oss::create_datatable_role(db, tx, cluster, name, password).await
+}
+
+/// Authorization: alters a cluster-wide Postgres login. Callers MUST restrict this to superadmin
+/// paths, and MUST hold [`lock_role_catalog`] on `tx`.
+pub async fn set_datatable_role_login(
+    db: &DB,
+    tx: &mut sqlx::Transaction<'_, sqlx::Postgres>,
+    cluster: DatatableRoleCluster,
+    name: &str,
+    enabled: bool,
+) -> Result<()> {
+    crate::datatable_roles_oss::set_datatable_role_login(db, tx, cluster, name, enabled).await
+}
+
+/// A rename discards an md5-hashed password, so the caller has to hand over a fresh one. On the
+/// external cluster the rename lands before `tx` commits, and callers MUST rename it back if `tx`
+/// then fails to commit.
+///
+/// Authorization: renames a cluster-wide Postgres login. Callers MUST restrict this to superadmin
+/// paths, and MUST hold [`lock_role_catalog`] on `tx`.
+pub async fn rename_datatable_role(
+    db: &DB,
+    tx: &mut sqlx::Transaction<'_, sqlx::Postgres>,
+    cluster: DatatableRoleCluster,
+    from: &str,
+    to: &str,
+    password: &str,
+) -> Result<()> {
+    crate::datatable_roles_oss::rename_datatable_role(db, tx, cluster, from, to, password).await
+}
+
+/// A role owning anything in any database blocks its own `DROP ROLE`, and both its objects and the
+/// privileges granted to it are only visible from inside each database — hence the pass over the
+/// registry. An unreachable database aborts the whole delete: dropping the role while one database
+/// still holds objects owned by it leaves those objects owned by a numeric OID nobody can name.
+///
+/// Each pass runs as the cluster's administrator rather than `custom_instance_user`: on Windmill's
+/// own cluster the instance's Postgres user, on the external one its configured admin login. Both
+/// own the databases and can therefore revoke a grant whoever made it. `custom_instance_user`
+/// could only undo what it granted itself, so a privilege planted by an operator in psql — the
+/// ordinary way privileges reach a role — would survive and block the drop.
+///
+/// Authorization: drops a cluster-wide Postgres login and reassigns everything it owns. Callers
+/// MUST restrict this to superadmin paths, and MUST hold [`lock_role_catalog`] on `tx`.
+///
+/// The per-database passes open their own connections and cannot join `tx`; the lock is what keeps
+/// a concurrent mutation out while they run. On Windmill's own cluster only the final `DROP ROLE`
+/// is on `tx`, so it commits or rolls back with the catalog write that forgets the role; on the
+/// external cluster it runs there, and tolerates a role already gone so a retry after a failed
+/// commit can finish. The passes commit as they go, so callers MUST have disabled the role in an
+/// earlier committed transaction: a failure part-way then leaves a disabled role to retry, not an
+/// enabled one already stripped in some databases.
+pub async fn drop_datatable_role(
+    db: &DB,
+    tx: &mut sqlx::Transaction<'_, sqlx::Postgres>,
+    cluster: DatatableRoleCluster,
+    name: &str,
+) -> Result<()> {
+    crate::datatable_roles_oss::drop_datatable_role(db, tx, cluster, name).await
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn role_names_are_validated() {
+        assert!(validate_role_name("analytics").is_ok());
+        assert!(validate_role_name("read-only_2").is_ok());
+        assert!(validate_role_name("").is_err());
+        assert!(validate_role_name(&"a".repeat(64)).is_err());
+        assert!(validate_role_name("has space").is_err());
+        assert!(validate_role_name("quote\"injection").is_err());
+        // Reserved, case-insensitively.
+        assert!(validate_role_name("admin").is_err());
+        assert!(validate_role_name("Postgres").is_err());
+        assert!(validate_role_name("pg_read_all_data").is_err());
+        assert!(validate_role_name("windmill_user").is_err());
+        assert!(validate_role_name("custom_instance_user").is_err());
+    }
+
+    #[test]
+    fn a_disabled_role_is_an_error_not_a_fallback() {
+        let mut catalog = DatatableRoleCatalog::new();
+        catalog.insert(
+            "id1".to_string(),
+            InstanceDatatableRole {
+                name: "analytics".to_string(),
+                enabled: false,
+                pwd: Some("x".to_string()),
+            },
+        );
+        assert!(role_id_by_name(&catalog, "analytics").is_err());
+        assert!(role_id_by_name(&catalog, "nope").is_err());
+        catalog.get_mut("id1").unwrap().enabled = true;
+        assert_eq!(role_id_by_name(&catalog, "analytics").unwrap(), "id1");
+    }
+}

backend/windmill-common/src/datatable_roles_oss.rs

@@ -0,0 +1,243 @@
+/*
+ * Author: Ruben Fiszel
+ * Copyright: Windmill Labs, Inc 2022
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the included NOTICE for copyright information and
+ * LICENSE-AGPL for a copy of the license.
+ */
+
+//! Where data table roles come from: the enterprise implementation, or a refusal.
+//!
+//! Roles are an Enterprise Edition feature. An edition without them creates, grants and connects
+//! as none, and a data table saved under roles — by an enterprise build, before a downgrade — is
+//! refused rather than resolved as `admin`. A data table not under roles, asked for no role,
+//! resolves as it always has. `private` alone is not that edition: community builds carry it.
+
+use crate::error::Error;
+
+/// What every roles path answers without the Enterprise Edition. The frontend matches this exact
+/// sentence (`datatableUsableRoles.ts`) to read the refusal as "not under roles": reword both.
+pub fn datatable_roles_unavailable() -> Error {
+    Error::BadRequest("Data table roles are a Windmill Enterprise Edition feature".to_string())
+}
+
+#[cfg(all(feature = "private", feature = "enterprise"))]
+pub(crate) use crate::datatable_roles_ee::{
+    can_use_datatable_role, can_use_datatable_role_in_governing_workspace, converge_connect_grants,
+    converge_connect_grants_with, create_datatable_role, delete_role_catalog_entry,
+    drop_datatable_role, ensure_can_use_datatable_role, ensure_datatable_admin_access,
+    ensure_instance_db_grant_options_unchecked, forget_datatable_role_everywhere,
+    insert_role_catalog_entry, read_role_catalog, read_role_catalog_tx,
+    registered_instance_databases, rename_datatable_role, resolve_datatable_role_connection,
+    role_cluster, set_datatable_role_login, update_role_catalog_entry,
+};
+
+#[cfg(not(all(feature = "private", feature = "enterprise")))]
+pub(crate) use ce::*;
+
+#[cfg(not(all(feature = "private", feature = "enterprise")))]
+mod ce {
+    use super::datatable_roles_unavailable as unavailable;
+    use crate::{
+        datatable_roles::{DatatableRoleCatalog, DatatableRoleCluster, InstanceDatatableRole},
+        db::AuthedRef,
+        error::Result,
+        workspaces::{
+            resolve_governing_datatable, DataTableRoleTenants, DatatableAccess, GoverningDatatable,
+        },
+        DB,
+    };
+
+    type Tx<'a> = sqlx::Transaction<'a, sqlx::Postgres>;
+
+    pub(crate) async fn read_role_catalog(
+        _db: &DB,
+        _cluster: DatatableRoleCluster,
+    ) -> Result<DatatableRoleCatalog> {
+        Err(unavailable())
+    }
+
+    pub(crate) async fn read_role_catalog_tx(
+        _tx: &mut Tx<'_>,
+        _cluster: DatatableRoleCluster,
+    ) -> Result<DatatableRoleCatalog> {
+        Err(unavailable())
+    }
+
+    pub(crate) async fn role_cluster(
+        _tx: &mut Tx<'_>,
+        _id: &str,
+    ) -> Result<Option<DatatableRoleCluster>> {
+        Err(unavailable())
+    }
+
+    pub(crate) async fn insert_role_catalog_entry(
+        _tx: &mut Tx<'_>,
+        _id: &str,
+        _cluster: DatatableRoleCluster,
+        _role: &InstanceDatatableRole,
+    ) -> Result<()> {
+        Err(unavailable())
+    }
+
+    pub(crate) async fn update_role_catalog_entry(
+        _tx: &mut Tx<'_>,
+        _id: &str,
+        _role: &InstanceDatatableRole,
+    ) -> Result<()> {
+        Err(unavailable())
+    }
+
+    pub(crate) async fn delete_role_catalog_entry(_tx: &mut Tx<'_>, _id: &str) -> Result<()> {
+        Err(unavailable())
+    }
+
+    pub(crate) async fn registered_instance_databases(
+        _db: &DB,
+        _cluster: DatatableRoleCluster,
+    ) -> Result<Vec<String>> {
+        Err(unavailable())
+    }
+
+    /// Nothing to converge: with no roles to admit, a managed database keeps the `CONNECT` grants
+    /// it was created with, as it did before roles existed.
+    pub(crate) async fn converge_connect_grants(
+        _db: &DB,
+        _cluster: DatatableRoleCluster,
+        _dbname: &str,
+    ) -> Result<()> {
+        Ok(())
+    }
+
+    /// As [`converge_connect_grants`].
+    pub(crate) async fn converge_connect_grants_with(
+        _db: &DB,
+        _cluster: DatatableRoleCluster,
+        _dbname: &str,
+        _catalog: &DatatableRoleCatalog,
+    ) -> Result<()> {
+        Ok(())
+    }
+
+    pub(crate) async fn create_datatable_role(
+        _db: &DB,
+        _tx: &mut Tx<'_>,
+        _cluster: DatatableRoleCluster,
+        _name: &str,
+        _password: &str,
+    ) -> Result<()> {
+        Err(unavailable())
+    }
+
+    pub(crate) async fn set_datatable_role_login(
+        _db: &DB,
+        _tx: &mut Tx<'_>,
+        _cluster: DatatableRoleCluster,
+        _name: &str,
+        _enabled: bool,
+    ) -> Result<()> {
+        Err(unavailable())
+    }
+
+    pub(crate) async fn rename_datatable_role(
+        _db: &DB,
+        _tx: &mut Tx<'_>,
+        _cluster: DatatableRoleCluster,
+        _from: &str,
+        _to: &str,
+        _password: &str,
+    ) -> Result<()> {
+        Err(unavailable())
+    }
+
+    pub(crate) async fn drop_datatable_role(
+        _db: &DB,
+        _tx: &mut Tx<'_>,
+        _cluster: DatatableRoleCluster,
+        _name: &str,
+    ) -> Result<()> {
+        Err(unavailable())
+    }
+
+    pub(crate) async fn ensure_instance_db_grant_options_unchecked(
+        _db: &DB,
+        _cluster: DatatableRoleCluster,
+        _dbname: &str,
+    ) -> Result<()> {
+        Err(unavailable())
+    }
+
+    /// No tenant list covers anyone: there is no role to connect as.
+    pub(crate) fn can_use_datatable_role(
+        _tenants: &DataTableRoleTenants,
+        _authed: &AuthedRef<'_>,
+    ) -> bool {
+        false
+    }
+
+    pub(crate) async fn can_use_datatable_role_in_governing_workspace(
+        _db: &DB,
+        _governing_w_id: &str,
+        _w_id: &str,
+        _tenants: &DataTableRoleTenants,
+        _access: &DatatableAccess<'_>,
+    ) -> Result<bool> {
+        Err(unavailable())
+    }
+
+    /// Reached only for a data table under roles or a caller naming a role: both are refused.
+    pub(crate) async fn resolve_datatable_role_connection(
+        _db: &DB,
+        _w_id: &str,
+        _name: &str,
+        _governing: &GoverningDatatable,
+        _db_resource: serde_json::Value,
+        _role: Option<&str>,
+        _access: DatatableAccess<'_>,
+    ) -> Result<serde_json::Value> {
+        Err(unavailable())
+    }
+
+    /// A data table not under roles, asked for no role or for `admin`, is not a role decision and
+    /// passes, as it did before roles existed. Anything else is refused.
+    pub(crate) async fn ensure_can_use_datatable_role(
+        db: &DB,
+        w_id: &str,
+        name: &str,
+        role: Option<&str>,
+        _access: &DatatableAccess<'_>,
+        _context: &str,
+    ) -> Result<()> {
+        let governing = resolve_governing_datatable(db, w_id, name).await?;
+        if governing.datatable.permissions.is_none()
+            && role.is_none_or(|r| r == crate::datatable_roles::ADMIN_DATATABLE_ROLE)
+        {
+            Ok(())
+        } else {
+            Err(unavailable())
+        }
+    }
+
+    /// A data table not under roles is the `admin` connection for anyone who reaches it, as before
+    /// roles existed. One under roles is refused.
+    pub(crate) async fn ensure_datatable_admin_access(
+        db: &DB,
+        w_id: &str,
+        name: &str,
+        _access: &DatatableAccess<'_>,
+    ) -> Result<()> {
+        let governing = resolve_governing_datatable(db, w_id, name).await?;
+        if governing.datatable.permissions.is_none() {
+            Ok(())
+        } else {
+            Err(unavailable())
+        }
+    }
+
+    pub(crate) async fn forget_datatable_role_everywhere(
+        _tx: &mut Tx<'_>,
+        _role_id: &str,
+    ) -> Result<()> {
+        Err(unavailable())
+    }
+}

backend/windmill-common/src/external_instance_pg.rs

@@ -0,0 +1,439 @@
+/*
+ * Author: Ruben Fiszel
+ * Copyright: Windmill Labs, Inc 2022
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the included NOTICE for copyright information and
+ * LICENSE-AGPL for a copy of the license.
+ */
+
+//! The external Postgres cluster behind `external_instance` data tables and Ducklake catalogs.
+//!
+//! Windmill administers that cluster itself, logged in as the user in
+//! [`EXTERNAL_INSTANCE_PG_SETTING`]. It creates `custom_instance_user` and
+//! `custom_instance_replication_user` there, with passwords it generates and keeps in
+//! [`EXTERNAL_INSTANCE_PG_STATE_SETTING`]. They share their names with the roles on Windmill's own
+//! cluster, but they are different roles with different passwords.
+//!
+//! The cluster may hold data Windmill did not create. Two Windmill instances sharing one is not
+//! supported: each would keep resetting the passwords the other depends on.
+
+use std::collections::{BTreeMap, BTreeSet};
+
+use serde::{Deserialize, Serialize};
+
+use crate::{
+    error::{Error, Result},
+    global_settings::{EXTERNAL_INSTANCE_PG_SETTING, EXTERNAL_INSTANCE_PG_STATE_SETTING},
+    instance_config::{CustomInstanceDb, ExternalInstancePg},
+    DB,
+};
+
+/// What Windmill keeps about the external cluster. Server-managed and hidden: never part of the
+/// instance config, never readable by an agent worker. No `Debug`: it carries live passwords.
+#[derive(Serialize, Deserialize, Clone, Default)]
+pub struct ExternalInstancePgState {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub user_pwd: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub replication_pwd: Option<String>,
+    /// The databases Windmill created on the cluster. It only ever drops one of these.
+    #[serde(default)]
+    pub databases: BTreeMap<String, CustomInstanceDb>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub last_setup: Option<ExternalInstancePgSetupReport>,
+    /// The cluster ([`external_instance_pg_address`]) the last successful setup converged. Databases
+    /// are only created on a cluster setup succeeded on: the passwords above exist as soon as setup
+    /// first runs, whether or not the cluster accepted them.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub set_up_for: Option<String>,
+}
+
+/// What identifies the cluster a configuration points at. Other fields (admin login, sslmode) can
+/// change without it becoming another cluster.
+pub fn external_instance_pg_address(config: &ExternalInstancePg) -> String {
+    format!(
+        "{}:{}",
+        config.host.trim().to_lowercase(),
+        config.port.unwrap_or(5432)
+    )
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug)]
+pub struct ExternalInstancePgSetupReport {
+    /// No step failed. Warnings leave it true.
+    pub success: bool,
+    pub finished_at: chrono::DateTime<chrono::Utc>,
+    pub steps: Vec<ExternalInstancePgSetupStep>,
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug)]
+pub struct ExternalInstancePgSetupStep {
+    pub name: String,
+    pub status: SetupStepStatus,
+    pub message: String,
+}
+
+#[derive(Serialize, Deserialize, Clone, Copy, Debug, PartialEq, Eq)]
+#[serde(rename_all = "lowercase")]
+pub enum SetupStepStatus {
+    Ok,
+    Warning,
+    Error,
+}
+
+/// The status the settings page shows without running anything.
+#[derive(Serialize, Debug)]
+pub struct ExternalInstancePgStatus {
+    pub configured: bool,
+    pub database_count: usize,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub last_setup: Option<ExternalInstancePgSetupReport>,
+}
+
+/// Authorization: returns the cluster's admin password and checks nothing. Callers MUST be
+/// superadmin or an internal server path.
+pub(crate) async fn read_external_instance_pg_config<'c>(
+    executor: impl sqlx::PgExecutor<'c>,
+) -> Result<Option<ExternalInstancePg>> {
+    let value = sqlx::query_scalar!(
+        "SELECT value FROM global_settings WHERE name = $1",
+        EXTERNAL_INSTANCE_PG_SETTING
+    )
+    .fetch_optional(executor)
+    .await?;
+    value
+        .map(|v| {
+            serde_json::from_value(v).map_err(|e| {
+                Error::internal_err(format!("reading {EXTERNAL_INSTANCE_PG_SETTING}: {e}"))
+            })
+        })
+        .transpose()
+}
+
+/// Authorization: returns the passwords Windmill generated on the cluster and checks nothing.
+/// Callers MUST be superadmin or an internal server path.
+pub(crate) async fn read_external_instance_pg_state<'c>(
+    executor: impl sqlx::PgExecutor<'c>,
+) -> Result<ExternalInstancePgState> {
+    let value = sqlx::query_scalar!(
+        "SELECT value FROM global_settings WHERE name = $1",
+        EXTERNAL_INSTANCE_PG_STATE_SETTING
+    )
+    .fetch_optional(executor)
+    .await?;
+    match value {
+        None => Ok(ExternalInstancePgState::default()),
+        Some(v) => serde_json::from_value(v).map_err(|e| {
+            Error::internal_err(format!("reading {EXTERNAL_INSTANCE_PG_STATE_SETTING}: {e}"))
+        }),
+    }
+}
+
+pub async fn external_instance_pg_status(db: &DB) -> Result<ExternalInstancePgStatus> {
+    let configured = read_external_instance_pg_config(db).await?.is_some();
+    let state = read_external_instance_pg_state(db).await?;
+    Ok(ExternalInstancePgStatus {
+        configured,
+        database_count: state.databases.len(),
+        last_setup: state.last_setup,
+    })
+}
+
+/// The databases Windmill created on the external cluster, without the passwords kept beside them.
+///
+/// Authorization: names every database across all workspaces, and the workspace each fork copy is
+/// reserved for, and checks nothing. Callers MUST be superadmin or an internal authorization or
+/// lifecycle path that does not return the names to a workspace caller.
+pub async fn external_instance_databases(db: &DB) -> Result<BTreeMap<String, CustomInstanceDb>> {
+    Ok(read_external_instance_pg_state(db).await?.databases)
+}
+
+/// The workspaces whose data tables or Ducklake catalogs name each database on the external cluster,
+/// and the forks whose Ducklake metadata schemas there are still waiting to be dropped: those rows
+/// outlive a settings change, and cleanup cannot drop a schema in a database that is gone. A row
+/// whose schema is already dropped only waits on object storage, which needs no database.
+///
+/// Authorization: reads every workspace's settings and checks nothing. Callers MUST be superadmin
+/// or an internal lifecycle path.
+pub async fn external_instance_database_usages<'c>(
+    db: impl sqlx::PgExecutor<'c>,
+) -> Result<BTreeMap<String, BTreeSet<String>>> {
+    let rows = sqlx::query_as::<_, (String, String)>(
+        "SELECT ws.workspace_id, entry->'database'->>'resource_path'
+         FROM workspace_settings ws
+         CROSS JOIN LATERAL jsonb_each(
+             CASE WHEN jsonb_typeof(ws.datatable->'datatables') = 'object'
+                 THEN ws.datatable->'datatables'
+                 ELSE '{}'::jsonb END
+         ) AS dt(k, entry)
+         WHERE entry->'database'->>'resource_type' = 'external_instance'
+           AND entry->'database'->>'resource_path' IS NOT NULL
+         UNION ALL
+         SELECT ws.workspace_id, entry->'catalog'->>'resource_path'
+         FROM workspace_settings ws
+         CROSS JOIN LATERAL jsonb_each(
+             CASE WHEN jsonb_typeof(ws.ducklake->'ducklakes') = 'object'
+                 THEN ws.ducklake->'ducklakes'
+                 ELSE '{}'::jsonb END
+         ) AS dl(k, entry)
+         WHERE entry->'catalog'->>'resource_type' = 'external_instance'
+           AND entry->'catalog'->>'resource_path' IS NOT NULL
+         UNION ALL
+         SELECT workspace_id, substring(catalog FROM length('external_instance:') + 1)
+         FROM fork_ducklake_namespace
+         WHERE catalog LIKE 'external\\_instance:%' AND NOT schema_dropped",
+    )
+    .fetch_all(db)
+    .await?;
+    let mut usages: BTreeMap<String, BTreeSet<String>> = BTreeMap::new();
+    for (workspace_id, dbname) in rows {
+        usages.entry(dbname).or_default().insert(workspace_id);
+    }
+    Ok(usages)
+}
+
+/// Refuse to unset the cluster while Windmill still has databases or data table roles on it, or a
+/// workspace still points at one: every data table there would stop resolving, and every role
+/// would be a login nothing can drop any more. Allowed on every edition, so a
+/// downgraded instance can still clear a setting it no longer uses.
+pub async fn ensure_external_instance_pg_removable(db: &DB) -> Result<()> {
+    ensure_external_instance_pg_unused(db, &format!("removing {EXTERNAL_INSTANCE_PG_SETTING}"))
+        .await
+}
+
+/// Refuse while Windmill has databases or data table roles on the cluster, or a workspace points
+/// at one of its databases. `before` finishes the sentence saying what to do first.
+async fn ensure_external_instance_pg_unused(db: &DB, before: &str) -> Result<()> {
+    let state = read_external_instance_pg_state(db).await?;
+    let usages = external_instance_database_usages(db).await?;
+    let roles = sqlx::query_scalar::<_, String>(
+        "SELECT name FROM datatable_role WHERE cluster = 'external_instance' ORDER BY name",
+    )
+    .fetch_all(db)
+    .await?;
+    if state.databases.is_empty() && usages.is_empty() && roles.is_empty() {
+        return Ok(());
+    }
+    let mut held = vec![];
+    if !(state.databases.is_empty() && usages.is_empty()) {
+        let names = state
+            .databases
+            .keys()
+            .chain(usages.keys())
+            .collect::<BTreeSet<_>>()
+            .into_iter()
+            .cloned()
+            .collect::<Vec<_>>()
+            .join(", ");
+        held.push(format!("databases in use ({names})"));
+    }
+    if !roles.is_empty() {
+        held.push(format!("data table roles ({})", roles.join(", ")));
+    }
+    Err(Error::BadRequest(format!(
+        "The external instance cluster still holds {}. Drop them and repoint the data tables and \
+         Ducklake catalogs using them before {before}.",
+        held.join(" and ")
+    )))
+}
+
+/// Refuse a workspace setting that newly names an `external_instance` database on an edition
+/// without them.
+pub fn ensure_external_instance_available() -> Result<()> {
+    crate::external_instance_pg_oss::ensure_external_instance_available()
+}
+
+/// The connection an `external_instance` database resolves to: `custom_instance_user`, or the
+/// replication user, on the external cluster.
+///
+/// Authorization: returns live credentials and checks nothing. Callers MUST have authorized access
+/// to the data table that names `dbname`.
+pub async fn external_instance_connection_unchecked(
+    db: &DB,
+    dbname: &str,
+    replication: bool,
+) -> Result<crate::PgDatabase> {
+    crate::external_instance_pg_oss::external_instance_connection_unchecked(db, dbname, replication)
+        .await
+}
+
+/// Create `dbname` on the external cluster and register it. Refuses a name already taken there,
+/// whoever took it.
+///
+/// Authorization: checks nothing. Callers MUST be superadmin, or be cloning a data table they may
+/// fork into a `wm_fork_` database.
+pub async fn create_external_instance_database_unchecked(
+    db: &DB,
+    dbname: &str,
+    tag: &str,
+    for_workspace: Option<&str>,
+) -> Result<()> {
+    crate::external_instance_pg_oss::create_external_instance_database_unchecked(
+        db,
+        dbname,
+        tag,
+        for_workspace,
+    )
+    .await
+}
+
+/// Drop `dbname` from the external cluster: only a database Windmill registered creating, and still
+/// carries the mark it set there. Refused while anything uses it
+/// ([`crate::workspaces::managed_database_uses`]), except the `exempt` data table entry: the fork
+/// copy being cleaned up.
+///
+/// Authorization: checks nothing. Callers MUST be superadmin, or be deleting the fork that owns
+/// this `wm_fork_` database.
+pub async fn drop_external_instance_database_unchecked(
+    db: &DB,
+    dbname: &str,
+    exempt: Option<(&str, &str)>,
+) -> Result<()> {
+    crate::external_instance_pg_oss::drop_external_instance_database_unchecked(db, dbname, exempt)
+    .await
+}
+
+/// Serializes everything that changes which databases exist on the external cluster, or which data
+/// tables name them: setup, creates, drops, and data table saves. Held until `tx` ends.
+pub async fn lock_external_instance_pg_state(
+    tx: &mut sqlx::Transaction<'_, sqlx::Postgres>,
+) -> Result<()> {
+    sqlx::query("SELECT pg_advisory_xact_lock(hashtext($1))")
+        .bind(EXTERNAL_INSTANCE_PG_STATE_SETTING)
+        .execute(&mut **tx)
+        .await?;
+    Ok(())
+}
+
+/// Refuse a data table naming `dbname` unless Windmill created it on the external cluster. Takes
+/// the lock drops take, so none can remove the database before `tx`, which saves the data table,
+/// commits.
+pub async fn ensure_external_instance_database_registered(
+    tx: &mut sqlx::Transaction<'_, sqlx::Postgres>,
+    dbname: &str,
+) -> Result<()> {
+    lock_external_instance_pg_state(tx).await?;
+    if read_external_instance_pg_state(&mut **tx)
+        .await?
+        .databases
+        .contains_key(dbname)
+    {
+        return Ok(());
+    }
+    Err(Error::BadRequest(format!(
+        "Windmill did not create a database named '{dbname}' on the external instance cluster. \
+         Create it from the instance settings first."
+    )))
+}
+
+/// Write [`EXTERNAL_INSTANCE_PG_SETTING`]: `None`, null or an empty string unsets it. Every writer
+/// of global settings goes through this for that key — the per-key and bulk endpoints as well as
+/// the declarative sync — instead of writing the row itself.
+///
+/// The checks and the write share one transaction holding [`lock_external_instance_pg_state`]. A
+/// check taken outside it could pass while a database create still reads the old cluster, which
+/// would then register a database there after the setting names another one.
+///
+/// Authorization: checks nothing. Callers MUST be superadmin, or the declarative instance config
+/// sync, which applies what the operator deployed.
+pub async fn write_external_instance_pg_setting(
+    db: &DB,
+    value: Option<&serde_json::Value>,
+) -> Result<()> {
+    let value = match value {
+        None | Some(serde_json::Value::Null) => None,
+        Some(serde_json::Value::String(s)) if s.trim().is_empty() => None,
+        Some(value) => Some(value),
+    };
+    let mut tx = db.begin().await?;
+    lock_external_instance_pg_state(&mut tx).await?;
+    match value {
+        None => {
+            ensure_external_instance_pg_removable(db).await?;
+            sqlx::query("DELETE FROM global_settings WHERE name = $1")
+                .bind(EXTERNAL_INSTANCE_PG_SETTING)
+                .execute(&mut *tx)
+                .await?;
+        }
+        Some(value) => {
+            crate::external_instance_pg_oss::validate_external_instance_pg_setting(value)?;
+            ensure_external_instance_pg_not_repointed(db, value).await?;
+            sqlx::query(
+                "INSERT INTO global_settings (name, value) VALUES ($1, $2)
+                 ON CONFLICT (name) DO UPDATE SET value = EXCLUDED.value, updated_at = now()",
+            )
+            .bind(EXTERNAL_INSTANCE_PG_SETTING)
+            .bind(value)
+            .execute(&mut *tx)
+            .await?;
+        }
+    }
+    tx.commit().await?;
+    tracing::info!(
+        "{} global setting {EXTERNAL_INSTANCE_PG_SETTING}",
+        if value.is_some() { "Set" } else { "Unset" }
+    );
+    Ok(())
+}
+
+/// [`write_external_instance_pg_setting`] for a settings diff: writes the key if the diff touches
+/// it, and takes it out of the diff so the generic apply does not write it again.
+///
+/// Authorization: checks nothing. Callers MUST be superadmin, or the declarative instance config
+/// sync, which applies what the operator deployed.
+pub async fn write_external_instance_pg_from_diff(
+    db: &DB,
+    diff: &mut crate::instance_config::SettingsDiff,
+) -> Result<()> {
+    if let Some(value) = diff.upserts.remove(EXTERNAL_INSTANCE_PG_SETTING) {
+        write_external_instance_pg_setting(db, Some(&value)).await?;
+    }
+    if let Some(i) = diff
+        .deletes
+        .iter()
+        .position(|k| k == EXTERNAL_INSTANCE_PG_SETTING)
+    {
+        diff.deletes.remove(i);
+        write_external_instance_pg_setting(db, None).await?;
+    }
+    Ok(())
+}
+
+/// Refuse pointing the setting at another host or port while databases or data table roles live on
+/// the current one. Data tables name databases, and the role catalog names logins, not clusters, so
+/// both would silently resolve to whatever the new cluster holds under the same names. Other fields
+/// (admin login, sslmode) may change freely.
+async fn ensure_external_instance_pg_not_repointed(
+    db: &DB,
+    value: &serde_json::Value,
+) -> Result<()> {
+    let Some(current) = read_external_instance_pg_config(db).await? else {
+        return Ok(());
+    };
+    let Ok(desired) = serde_json::from_value::<ExternalInstancePg>(value.clone()) else {
+        return Ok(());
+    };
+    if external_instance_pg_address(&current) == external_instance_pg_address(&desired) {
+        return Ok(());
+    }
+    ensure_external_instance_pg_unused(
+        db,
+        &format!("pointing {EXTERNAL_INSTANCE_PG_SETTING} at another cluster"),
+    )
+    .await
+}
+
+/// Converge the external cluster on the configured login: check what it can do, create or update
+/// Windmill's two roles with the stored passwords, and report anything that would get in the way.
+/// With `rotate_passwords`, generate new passwords first. Safe to run again; running it again is
+/// how a failed rotation is repaired.
+///
+/// Authorization: administers the external cluster with its admin credentials and checks nothing.
+/// Callers MUST be superadmin.
+pub async fn setup_external_instance_pg_unchecked(
+    db: &DB,
+    rotate_passwords: bool,
+) -> Result<ExternalInstancePgSetupReport> {
+    crate::external_instance_pg_oss::setup_external_instance_pg_unchecked(db, rotate_passwords)
+        .await
+}

backend/windmill-common/src/external_instance_pg_oss.rs

@@ -0,0 +1,81 @@
+/*
+ * Author: Ruben Fiszel
+ * Copyright: Windmill Labs, Inc 2022
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the included NOTICE for copyright information and
+ * LICENSE-AGPL for a copy of the license.
+ */
+
+//! Where the external instance cluster comes from: the enterprise implementation, or a refusal.
+//! `private` alone is not that edition: community builds carry it.
+
+use crate::error::Error;
+
+pub fn external_instance_pg_unavailable() -> Error {
+    Error::BadRequest(
+        "External instance databases are a Windmill Enterprise Edition feature".to_string(),
+    )
+}
+
+#[cfg(all(feature = "private", feature = "enterprise"))]
+pub(crate) use crate::external_instance_pg_ee::{
+    create_external_instance_database_unchecked, drop_external_instance_database_unchecked,
+    external_instance_connection_unchecked, setup_external_instance_pg_unchecked,
+    validate_external_instance_pg_setting,
+};
+
+#[cfg(all(feature = "private", feature = "enterprise"))]
+pub(crate) fn ensure_external_instance_available() -> crate::error::Result<()> {
+    Ok(())
+}
+
+#[cfg(not(all(feature = "private", feature = "enterprise")))]
+pub(crate) use ce::*;
+
+#[cfg(not(all(feature = "private", feature = "enterprise")))]
+mod ce {
+    use super::external_instance_pg_unavailable as unavailable;
+    use crate::{
+        error::Result, external_instance_pg::ExternalInstancePgSetupReport, PgDatabase, DB,
+    };
+
+    pub(crate) fn validate_external_instance_pg_setting(_value: &serde_json::Value) -> Result<()> {
+        Err(unavailable())
+    }
+
+    pub(crate) fn ensure_external_instance_available() -> Result<()> {
+        Err(unavailable())
+    }
+
+    pub(crate) async fn setup_external_instance_pg_unchecked(
+        _db: &DB,
+        _rotate_passwords: bool,
+    ) -> Result<ExternalInstancePgSetupReport> {
+        Err(unavailable())
+    }
+
+    pub(crate) async fn external_instance_connection_unchecked(
+        _db: &DB,
+        _dbname: &str,
+        _replication: bool,
+    ) -> Result<PgDatabase> {
+        Err(unavailable())
+    }
+
+    pub(crate) async fn create_external_instance_database_unchecked(
+        _db: &DB,
+        _dbname: &str,
+        _tag: &str,
+        _for_workspace: Option<&str>,
+    ) -> Result<()> {
+        Err(unavailable())
+    }
+
+    pub(crate) async fn drop_external_instance_database_unchecked(
+        _db: &DB,
+        _dbname: &str,
+        _exempt: Option<(&str, &str)>,
+    ) -> Result<()> {
+        Err(unavailable())
+    }
+}

backend/windmill-common/src/global_settings.rs

@@ -57,6 +57,8 @@ pub const SAML_METADATA_SETTING: &str = "saml_metadata";
 pub const SMTP_SETTING: &str = "smtp_settings";
 pub const TEAMS_SETTING: &str = "teams";
 pub const INDEXER_SETTING: &str = "indexer_settings";
+pub const EXTERNAL_INSTANCE_PG_SETTING: &str = "external_instance_pg";
+pub const EXTERNAL_INSTANCE_PG_STATE_SETTING: &str = "external_instance_pg_state";
 pub const TIMEOUT_WAIT_RESULT_SETTING: &str = "timeout_wait_result";
 
 pub const UNIQUE_ID_SETTING: &str = "uid";
@@ -355,6 +357,9 @@ pub const AGENT_WORKER_BLOCKED_SETTINGS: &[&str] = &[
     // resolve datatable connections through the dedicated datatable endpoints, never these.
     "custom_instance_pg_databases",
     "custom_instance_replication_pwd",
+    // The external cluster's admin login, and the passwords Windmill generated on it.
+    EXTERNAL_INSTANCE_PG_SETTING,
+    EXTERNAL_INSTANCE_PG_STATE_SETTING,
 ];
 
 /// Whether an agent worker may read the given global setting over HTTP.

backend/windmill-common/src/instance_config.rs

@@ -350,6 +350,8 @@ pub struct GlobalSettings {
     pub ducklake_settings: Option<DucklakeSettings>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub custom_instance_pg_databases: Option<CustomInstancePgDatabases>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub external_instance_pg: Option<ExternalInstancePg>,
 
     // Opaque settings (EE-private structs or no clear schema)
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -809,6 +811,9 @@ pub struct CustomInstanceDb {
     pub error: Option<String>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub tag: Option<String>,
+    /// The workspace a member created this fork copy for. Absent when a superadmin created it.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub workspace_id: Option<String>,
 }
 
 /// Setup log entries for a custom instance database.
@@ -833,6 +838,36 @@ pub struct CustomInstanceDbLogs {
     pub replication_user_error: Option<String>,
 }
 
+// ---------------------------------------------------------------------------
+// External instance PG cluster
+// ---------------------------------------------------------------------------
+
+/// The external Postgres cluster Windmill manages for `external_instance` data tables and Ducklake
+/// catalogs. `user` logs in as the cluster's administrator: it needs `CREATEDB` and `CREATEROLE`.
+/// `dbname` is only where that login connects to run cluster-wide statements.
+///
+/// Every field defaults rather than being required: this deserializes as part of the whole
+/// instance config, and one malformed row must not make every other setting unreadable. The
+/// write path and every use reject an incomplete value instead.
+#[derive(Deserialize, Serialize, Clone, Debug, Default)]
+#[cfg_attr(feature = "instance_config_schema", derive(schemars::JsonSchema))]
+pub struct ExternalInstancePg {
+    #[serde(default)]
+    pub host: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub port: Option<u16>,
+    #[serde(default)]
+    pub user: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub password: Option<StringOrSecretRef>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub dbname: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub sslmode: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub root_certificate_pem: Option<String>,
+}
+
 // ---------------------------------------------------------------------------
 // Autoscaling (worker config)
 // ---------------------------------------------------------------------------
@@ -969,6 +1004,7 @@ pub const PROTECTED_SETTINGS: &[&str] = &[
     "ducklake_settings",
     "custom_instance_pg_databases",
     "custom_instance_replication_pwd",
+    "external_instance_pg_state",
     "uid",
     "rsa_keys",
     "jwt_secret",
@@ -994,6 +1030,8 @@ pub const HIDDEN_SETTINGS: &[&str] = &[
     // Server-only (written by setup/refresh via direct SQL), never operator-authored —
     // hidden so the config machinery can't read, rewrite, or drop it.
     "custom_instance_replication_pwd",
+    // Same for the passwords and database registry Windmill keeps for the external cluster.
+    "external_instance_pg_state",
 ];
 
 /// Top-level settings whose entire value is sensitive and must be fully redacted in logs.
@@ -1005,6 +1043,7 @@ const SENSITIVE_SETTINGS: &[&str] = &[
     "license_key",
     "ducklake_user_pg_pwd",
     "custom_instance_replication_pwd",
+    "external_instance_pg_state",
     "pip_index_url",
     "pip_extra_index_url",
     "npm_config_registry",
@@ -1030,6 +1069,7 @@ const NESTED_SENSITIVE_FIELDS: &[(&str, &[&str])] = &[
         &["secret_key", "serviceAccountKey"],
     ),
     ("custom_instance_pg_databases", &["user_pwd"]),
+    ("external_instance_pg", &["password"]),
 ];
 
 fn redact_json_value(value: &serde_json::Value) -> serde_json::Value {
@@ -1358,7 +1398,8 @@ pub async fn sync_global_settings_declarative(
     crate::global_settings::parse_allowed_origins_setting(desired.get(origins_key))
         .map_err(|e| anyhow::anyhow!("{origins_key}: {e}"))?;
 
-    let diff = diff_global_settings(current, desired, ApplyMode::Replace);
+    let mut diff = diff_global_settings(current, desired, ApplyMode::Replace);
+    crate::external_instance_pg::write_external_instance_pg_from_diff(db, &mut diff).await?;
     apply_settings_diff(db, &diff).await?;
 
     Ok(())
@@ -1491,6 +1532,10 @@ pub fn resolve_env_refs(settings: &mut GlobalSettings) -> Result<(), String> {
         resolve_env_option(&mut pg.user_pwd)?;
     }
 
+    if let Some(pg) = &mut settings.external_instance_pg {
+        resolve_env_option(&mut pg.password)?;
+    }
+
     Ok(())
 }
 
@@ -2460,39 +2505,33 @@ mod tests {
     }
 
     #[test]
-    fn custom_instance_replication_pwd_is_isolated_from_config() {
-        // The replication-role password is server-only: written by setup/refresh via direct
-        // SQL, never operator-authored. It must stay out of the declarative config surface
-        // (hidden on read) and be undeletable, so config sync can't read, rewrite, or drop it.
-        assert!(HIDDEN_SETTINGS.contains(&"custom_instance_replication_pwd"));
-        assert!(PROTECTED_SETTINGS.contains(&"custom_instance_replication_pwd"));
-        assert!(SENSITIVE_SETTINGS.contains(&"custom_instance_replication_pwd"));
+    fn server_generated_db_passwords_are_isolated_from_config() {
+        // These hold passwords the server generates: written by setup/refresh via direct SQL,
+        // never operator-authored. They must stay out of the declarative config surface
+        // (hidden on read) and be undeletable, so config sync can't read, rewrite, or drop them.
+        for key in [
+            "custom_instance_replication_pwd",
+            "external_instance_pg_state",
+        ] {
+            assert!(HIDDEN_SETTINGS.contains(&key), "{key}");
+            assert!(PROTECTED_SETTINGS.contains(&key), "{key}");
+            assert!(SENSITIVE_SETTINGS.contains(&key), "{key}");
 
-        // A stray desired value (e.g. flattened into `extra`) is ignored, not upserted.
-        let mut desired = BTreeMap::new();
-        desired.insert(
-            "custom_instance_replication_pwd".to_string(),
-            serde_json::json!("attacker-set"),
-        );
-        let diff = diff_global_settings(&BTreeMap::new(), &desired, ApplyMode::Merge);
-        assert!(
-            diff.upserts.is_empty(),
-            "hidden setting must not be upserted"
-        );
+            // A stray desired value (e.g. flattened into `extra`) is ignored, not upserted.
+            let mut desired = BTreeMap::new();
+            desired.insert(key.to_string(), serde_json::json!("attacker-set"));
+            let diff = diff_global_settings(&BTreeMap::new(), &desired, ApplyMode::Merge);
+            assert!(diff.upserts.is_empty(), "{key} must not be upserted");
 
-        // A current value is never deleted by a Replace that omits it.
-        let mut current = BTreeMap::new();
-        current.insert(
-            "custom_instance_replication_pwd".to_string(),
-            serde_json::json!("live"),
-        );
-        let diff = diff_global_settings(&current, &BTreeMap::new(), ApplyMode::Replace);
-        assert!(
-            !diff
-                .deletes
-                .contains(&"custom_instance_replication_pwd".to_string()),
-            "hidden setting must not be deleted"
-        );
+            // A current value is never deleted by a Replace that omits it.
+            let mut current = BTreeMap::new();
+            current.insert(key.to_string(), serde_json::json!("live"));
+            let diff = diff_global_settings(&current, &BTreeMap::new(), ApplyMode::Replace);
+            assert!(
+                !diff.deletes.contains(&key.to_string()),
+                "{key} must not be deleted"
+            );
+        }
     }
 
     #[test]

backend/windmill-common/src/lib.rs

@@ -37,6 +37,10 @@ pub mod bench;
 pub mod cache;
 pub mod client;
 pub mod data_metrics;
+pub mod datatable_roles;
+#[cfg(all(feature = "private", feature = "enterprise"))]
+mod datatable_roles_ee;
+pub mod datatable_roles_oss;
 pub mod db;
 #[cfg(all(feature = "enterprise", feature = "private"))]
 mod db_entra_ee;
@@ -54,6 +58,10 @@ pub mod ee_oss;
 pub mod email_ee;
 pub mod email_oss;
 pub mod error;
+pub mod external_instance_pg;
+#[cfg(all(feature = "private", feature = "enterprise"))]
+mod external_instance_pg_ee;
+pub mod external_instance_pg_oss;
 pub mod external_ip;
 #[cfg(feature = "private")]
 pub mod feature_usage_ee;
@@ -1020,6 +1028,20 @@ impl Future for TokioPgConnection {
     }
 }
 
+impl TokioPgConnection {
+    /// Drive the connection and hand back what the server sends outside of a query's response —
+    /// notices above all, which driving it as a future silently discards.
+    pub fn poll_message(
+        &mut self,
+        cx: &mut core::task::Context<'_>,
+    ) -> core::task::Poll<Option<Result<tokio_postgres::AsyncMessage, tokio_postgres::Error>>> {
+        match self {
+            TokioPgConnection::Tls(conn) => conn.poll_message(cx),
+            TokioPgConnection::NoTls(conn) => conn.poll_message(cx),
+        }
+    }
+}
+
 impl PgDatabase {
     /// The role the connection logs in as, whichever way it authenticates.
     pub fn login_name(&self) -> &str {
@@ -1064,7 +1086,13 @@ impl PgDatabase {
                 if err_str.contains("password authentication failed for user")
                     && err_str.contains("custom_instance_user")
                 {
-                    if let Some(db) = main_db {
+                    // The external instance cluster has a `custom_instance_user` of its own, whose
+                    // password setup manages. Rotating the local one would break every instance
+                    // data table and fix nothing.
+                    let local = PgDatabase::parse_uri(&get_database_url().await?.as_str().await)?;
+                    let on_local_cluster = local.host == self.host
+                        && local.port.unwrap_or(5432) == self.port.unwrap_or(5432);
+                    if let Some(db) = main_db.filter(|_| on_local_cluster) {
                         tracing::warn!(
                             "custom_instance_user password auth failed, refreshing and retrying..."
                         );
@@ -1514,12 +1542,51 @@ pub async fn drop_custom_instance_database(db: &DB, dbname: &str) -> error::Resu
     Ok(())
 }
 
+/// What `custom_instance_user` holds on an instance database.
+///
+/// `WITH GRANT OPTION` throughout: this is the connection every data table resolves to as `admin`,
+/// and it is the one that hands privileges to data table roles. Postgres refuses to let a role pass
+/// on a privilege it does not itself hold with grant option, so without these an admin could own
+/// the database and still be unable to grant `SELECT` on it to `analytics`.
+pub(crate) fn instance_db_grants(dbname: &str) -> String {
+    format!(
+        "GRANT CONNECT ON DATABASE \"{dbname}\" TO custom_instance_user WITH GRANT OPTION;
+         GRANT CREATE ON DATABASE \"{dbname}\" TO custom_instance_user WITH GRANT OPTION;
+         DO $$ BEGIN
+           IF EXISTS (SELECT 1 FROM pg_namespace WHERE nspname = 'public') THEN
+             GRANT USAGE ON SCHEMA public TO custom_instance_user WITH GRANT OPTION;
+             GRANT CREATE ON SCHEMA public TO custom_instance_user WITH GRANT OPTION;
+             ALTER DEFAULT PRIVILEGES IN SCHEMA public
+                 GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO custom_instance_user;
+           END IF;
+         END $$;"
+    )
+}
+
+/// Re-apply [`instance_db_grants`] to a managed database provisioned before data table roles
+/// existed, whose grants carry no grant option. Connects as the cluster's administrator — the
+/// database and `public` schema owner — since only it can hand out an option it holds.
+///
+/// Authorization: reaches a managed database with the server's own credentials and checks
+/// nothing. Callers MUST have authorized administration of `dbname` — superadmin, or an admin of
+/// the workspace governing a data table on it.
+pub async fn ensure_instance_db_grant_options_unchecked(
+    db: &DB,
+    cluster: crate::datatable_roles::DatatableRoleCluster,
+    dbname: &str,
+) -> error::Result<()> {
+    crate::datatable_roles_oss::ensure_instance_db_grant_options_unchecked(db, cluster, dbname)
+        .await
+}
+
 /// Create a custom instance database: CREATE DATABASE, grant permissions, register in global_settings.
-/// The `tag` is stored in global_settings metadata (e.g. "datatable" or "ducklake").
+/// The `tag` is stored in global_settings metadata (e.g. "datatable" or "ducklake"). `for_workspace`
+/// is the workspace a member creates a fork copy for; see [`ensure_fork_database_available_to`].
 pub async fn create_custom_instance_database(
     db: &DB,
     dbname: &str,
     tag: &str,
+    for_workspace: Option<&str>,
 ) -> error::Result<()> {
     let dbname = dbname.trim();
     validate_dbname(dbname)?;
@@ -1553,17 +1620,7 @@ pub async fn create_custom_instance_database(
     let (client, connection) = new_pg_creds.connect(Some(db)).await?;
     let join_handle = tokio::spawn(async move { connection.await });
 
-    if let Err(e) = client
-        .batch_execute(&format!(
-            "GRANT CONNECT ON DATABASE \"{dbname}\" TO custom_instance_user;
-             GRANT USAGE ON SCHEMA public TO custom_instance_user;
-             GRANT CREATE ON SCHEMA public TO custom_instance_user;
-             GRANT CREATE ON DATABASE \"{dbname}\" TO custom_instance_user;
-             ALTER DEFAULT PRIVILEGES IN SCHEMA public
-                 GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO custom_instance_user;"
-        ))
-        .await
-    {
+    if let Err(e) = client.batch_execute(&instance_db_grants(dbname)).await {
         tracing::warn!(
             "Failed to grant permissions on '{}': {}. Continuing.",
             dbname,
@@ -1583,7 +1640,8 @@ pub async fn create_custom_instance_database(
         },
         "success": true,
         "error": null,
-        "tag": tag
+        "tag": tag,
+        "workspace_id": for_workspace,
     });
     sqlx::query!(
         r#"UPDATE global_settings SET value = jsonb_set(value, '{databases}', (COALESCE(value->'databases', '{}'::jsonb) || to_jsonb($1::json))) WHERE name = 'custom_instance_pg_databases'"#,
@@ -1592,10 +1650,88 @@ pub async fn create_custom_instance_database(
     .execute(db)
     .await?;
 
+    // A data table role can only reach a database it may CONNECT to, and PUBLIC's default CONNECT
+    // would otherwise let every role in regardless of what this instance defines. Best-effort: a
+    // failure here leaves the database usable as `admin`, and the next role change repairs it.
+    if let Err(e) = crate::datatable_roles::converge_connect_grants(
+        db,
+        crate::datatable_roles::DatatableRoleCluster::Instance,
+        dbname,
+    )
+    .await
+    {
+        tracing::warn!("Could not set CONNECT grants on instance database '{dbname}': {e}");
+    }
+
     tracing::info!("Created custom instance database '{}'", dbname);
     Ok(())
 }
 
+/// The system's CA bundle file, for libpq clients that cannot take `sslrootcert=system`: that value
+/// needs libpq 16, and verify-full only.
+pub fn system_ca_bundle() -> Option<std::path::PathBuf> {
+    std::env::var_os("SSL_CERT_FILE")
+        .map(std::path::PathBuf::from)
+        .into_iter()
+        .chain(
+            [
+                "/etc/ssl/certs/ca-certificates.crt",
+                "/etc/pki/tls/certs/ca-bundle.crt",
+                "/etc/ssl/cert.pem",
+                "/etc/ssl/ca-bundle.pem",
+            ]
+            .map(std::path::PathBuf::from),
+        )
+        .find(|path| path.is_file())
+}
+
+/// Refuse a workspace member writing a fork copy into, or pointing a fork at, the managed database
+/// `dbname` of `kind`, unless `w_id` created it for that ([`create_custom_instance_database`], or
+/// its external instance counterpart) and nothing uses it yet. The `wm_fork_` prefix is no
+/// authorization: every database of a cluster answers to the same `custom_instance_user`, so a name
+/// is all it takes to reach another workspace's copy.
+///
+/// Authorization: reads the global registries and every workspace's settings, and names other
+/// workspaces in its refusal. Callers MUST have authorized `w_id` for the caller first — a member
+/// of it forking or importing there — and MUST NOT call it on a workspace the caller is not in.
+pub async fn ensure_fork_database_available_to(
+    db: &DB,
+    kind: workspaces::DataTableCatalogResourceType,
+    dbname: &str,
+    w_id: &str,
+) -> error::Result<()> {
+    let created_for = match kind {
+        workspaces::DataTableCatalogResourceType::ExternalInstance => {
+            external_instance_pg::external_instance_databases(db)
+                .await?
+                .remove(dbname)
+                .and_then(|entry| entry.workspace_id)
+        }
+        _ => sqlx::query_scalar::<_, Option<String>>(
+            "SELECT value->'databases'->$1->>'workspace_id' FROM global_settings
+             WHERE name = 'custom_instance_pg_databases'",
+        )
+        .bind(dbname)
+        .fetch_optional(db)
+        .await?
+        .flatten(),
+    };
+    if created_for.as_deref() != Some(w_id) {
+        return Err(Error::BadRequest(format!(
+            "Database '{dbname}' was not created for a fork of workspace '{w_id}'"
+        )));
+    }
+    let uses =
+        workspaces::managed_database_uses(&mut *db.acquire().await?, kind, dbname, None).await?;
+    if !uses.is_empty() {
+        return Err(Error::BadRequest(format!(
+            "Database '{dbname}' is already in use: {}",
+            uses.join(", ")
+        )));
+    }
+    Ok(())
+}
+
 /// Connection options parsed from a database URL.
 ///
 /// The only place a database URL becomes `PgConnectOptions`. Providers that mint the password

backend/windmill-common/src/query_builders.rs

@@ -329,6 +329,7 @@ pub fn try_expand_internal_db_query(
         "ALTER_TABLE" => expand_alter_table(json_str, db_type).map(ExpandedQuery::sql),
         "CREATE_SCHEMA" => expand_create_schema(json_str, db_type).map(ExpandedQuery::sql),
         "DROP_SCHEMA" => expand_drop_schema(json_str, db_type).map(ExpandedQuery::sql),
+        "RENAME_SCHEMA" => expand_rename_schema(json_str, db_type).map(ExpandedQuery::sql),
         // Metadata queries
         "LOAD_TABLE_METADATA" => expand_load_table_metadata(json_str, db_type),
         "FOREIGN_KEYS" => expand_foreign_keys(json_str, db_type).map(ExpandedQuery::sql),
@@ -1716,6 +1717,13 @@ struct DropSchemaPayload {
     ducklake: Option<String>,
 }
 
+#[derive(Deserialize)]
+struct RenameSchemaPayload {
+    schema: String,
+    new_schema: String,
+    ducklake: Option<String>,
+}
+
 #[derive(Debug, Clone, Deserialize)]
 struct TableEditorColumn {
     name: String,
@@ -2004,6 +2012,23 @@ fn expand_drop_schema(json_str: &str, db_type: DbType) -> Result<String, String>
     Ok(maybe_wrap_ducklake(query, p.ducklake.as_deref()))
 }
 
+fn expand_rename_schema(json_str: &str, db_type: DbType) -> Result<String, String> {
+    let p: RenameSchemaPayload = serde_json::from_str(json_str)
+        .map_err(|e| format!("Invalid RENAME_SCHEMA payload: {}", e))?;
+    if !matches!(db_type, DbType::Postgresql | DbType::Snowflake) || p.ducklake.is_some() {
+        return Err(format!(
+            "Renaming a schema is not supported on {:?}",
+            db_type
+        ));
+    }
+    let query = format!(
+        "ALTER SCHEMA {} RENAME TO {};",
+        qi(&p.schema, db_type),
+        qi(&p.new_schema, db_type)
+    );
+    Ok(query)
+}
+
 fn expand_create_table(json_str: &str, db_type: DbType) -> Result<String, String> {
     let p: CreateTablePayload = serde_json::from_str(json_str)
         .map_err(|e| format!("Invalid CREATE_TABLE payload: {}", e))?;
@@ -2598,7 +2623,9 @@ WHERE table_catalog = current_database()",
                 )
             } else {
                 (
-                    "\nWHERE c.relkind = 'r' AND a.attnum > 0 AND NOT a.attisdropped\n    AND ns.nspname != 'pg_catalog' AND ns.nspname != 'information_schema'".to_string(),
+                    // pg_catalog is readable by everyone: without the privilege check this lists
+                    // tables of schemas the connection's role cannot even enter.
+                    "\nWHERE c.relkind = 'r' AND a.attnum > 0 AND NOT a.attisdropped\n    AND ns.nspname != 'pg_catalog' AND ns.nspname != 'information_schema'\n    AND has_schema_privilege(ns.oid, 'USAGE')".to_string(),
                     ",\n    ns.nspname AS schema_name,\n    c.relname AS table_name".to_string(),
                     "\nJOIN pg_catalog.pg_class c ON a.attrelid = c.oid\nJOIN pg_catalog.pg_namespace ns ON c.relnamespace = ns.oid".to_string(),
                     "ns.nspname, c.relname, a.attnum".to_string(),
@@ -4101,6 +4128,13 @@ mod tests {
         assert_eq!(sql, "DROP SCHEMA \"old_schema\" CASCADE;");
     }
 
+    #[test]
+    fn test_expand_rename_schema() {
+        let marker = r#"-- WM_INTERNAL_DB_RENAME_SCHEMA {"schema":"old","new_schema":"new"}"#;
+        let sql = expand_code(marker, &ScriptLang::Postgresql);
+        assert_eq!(sql, "ALTER SCHEMA \"old\" RENAME TO \"new\";");
+    }
+
     #[test]
     fn test_expand_create_schema_with_ducklake() {
         let marker = r#"-- WM_INTERNAL_DB_CREATE_SCHEMA {"schema":"s","ducklake":"lake"}"#;
@@ -4468,6 +4502,7 @@ mod tests {
         assert!(sql.contains("schema_name"));
         assert!(sql.contains("table_name"));
         assert!(sql.contains("c.relkind = 'r'"));
+        assert!(sql.contains("has_schema_privilege(ns.oid, 'USAGE')"));
     }
 
     #[test]

backend/windmill-common/src/worker.rs

@@ -1082,6 +1082,83 @@ pub struct SqlAnnotations {
     pub raw_output: bool,
 }
 
+impl SqlAnnotations {
+    /// The data table role a query declares as `-- role <name>`, if any. Only meaningful against a
+    /// `datatable://` database that is under roles; absent means the data table's default role.
+    ///
+    /// Hand-written rather than derived because the value matters, not just the presence, and
+    /// because the executor needs it before it knows the connection is a data table at all. Like
+    /// every annotation it lives in the leading comment block.
+    ///
+    /// A leading comment whose first word is `role` is an annotation *attempt*, and a malformed
+    /// one is an error. The alternative — ignoring what does not parse — resolves the query to the
+    /// data table's default role instead, so a typo silently runs it under a login the author did
+    /// not choose, which is the opposite of what naming a role is for. Only callers that already
+    /// know the target is a `datatable://` reference ever run this, so ordinary SQL keeps its
+    /// comments.
+    pub fn datatable_role(code: &str) -> error::Result<Option<String>> {
+        for line in code.lines() {
+            let line = line.trim();
+            if line.is_empty() {
+                continue;
+            }
+            if !line.starts_with("--") {
+                break;
+            }
+            // The keyword may be followed by whitespace, `:` or `=` — `role x`, `role: x`,
+            // `role=x`, `Role = x` all open an attempt, while `rolexyz` does not. Each accepted
+            // separator is one spelling that would otherwise take the `continue` below and run the
+            // query as the data table's default role, which is the silence this exists to remove.
+            let body = line[2..].trim_start();
+            let Some(after) = body
+                .get(..4)
+                .filter(|kw| kw.eq_ignore_ascii_case("role"))
+                .map(|_| &body[4..])
+            else {
+                continue;
+            };
+            if !after.is_empty()
+                && !after.starts_with(char::is_whitespace)
+                && !after.starts_with([':', '='])
+            {
+                continue;
+            }
+
+            // Past this point the line is an attempt to name a role, so a malformed one is an
+            // error rather than a miss. Falling through would run the query as the data table's
+            // default role — quietly, and under a login the author did not choose.
+            let after = after.trim_start();
+            let after = after.strip_prefix([':', '=']).unwrap_or(after);
+            let mut tokens = after.split_whitespace();
+            let role = tokens
+                .next()
+                .map(|role| role.strip_suffix(';').unwrap_or(role));
+            let rest = tokens.next();
+            match (role, rest) {
+                (Some(role), None)
+                    if !role.is_empty()
+                        && role.len() <= 63
+                        && role
+                            .chars()
+                            .all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '-') =>
+                {
+                    return Ok(Some(role.to_string()));
+                }
+                _ => {
+                    return Err(error::Error::BadRequest(format!(
+                        "Malformed data table role annotation: `{line}`. Write it as \
+                         `-- role <name>` on a line of its own, where <name> is letters, digits, \
+                         '_' or '-'. A comment in the leading block that starts with the word \
+                         'role' is read as this annotation; move it below the first statement if \
+                         it is prose."
+                    )));
+                }
+            }
+        }
+        Ok(None)
+    }
+}
+
 #[annotations("#")]
 pub struct BashAnnotations {
     pub docker: bool,
@@ -2653,6 +2730,56 @@ mod tests {
     use super::*;
     use std::collections::HashMap;
 
+    #[test]
+    fn datatable_role_is_read_from_the_leading_comment_block() {
+        let role = |code| SqlAnnotations::datatable_role(code);
+        assert_eq!(
+            role("-- role analytics\nSELECT 1").unwrap(),
+            Some("analytics".to_string())
+        );
+        // Blank lines and other annotations before it are fine.
+        assert_eq!(
+            role("\n-- prepare\n-- role read_only\nSELECT 1").unwrap(),
+            Some("read_only".to_string())
+        );
+        // Past the first statement it is an ordinary comment, not an annotation.
+        assert_eq!(role("SELECT 1;\n-- role analytics").unwrap(), None);
+        assert_eq!(role("SELECT 1").unwrap(), None);
+
+        // Unambiguous intent is honoured: the keyword matches case-insensitively, a trailing
+        // semicolon is a habit carried over from SQL rather than a different role, and the colon
+        // spelling is the one most likely to be typed.
+        for accepted in [
+            "-- Role operator\nSELECT 1",
+            "-- role operator;\nSELECT 1",
+            "-- role: operator\nSELECT 1",
+            "-- role:operator\nSELECT 1",
+            "-- role=operator\nSELECT 1",
+            "-- Role = operator\nSELECT 1",
+        ] {
+            assert_eq!(
+                role(accepted).unwrap(),
+                Some("operator".to_string()),
+                "not honoured: {accepted}"
+            );
+        }
+
+        // Anything else opening with the word is refused rather than resolved to the default role:
+        // the whole point of naming one is to not run as something else.
+        for near_miss in [
+            "-- role operator -- why\nSELECT 1",
+            "-- role an;alytics\nSELECT 1",
+            "-- role\nSELECT 1",
+            "-- role:\nSELECT 1",
+            "-- role based access is handled below\nSELECT 1",
+        ] {
+            assert!(role(near_miss).is_err(), "silently ignored: {near_miss}");
+        }
+
+        // A word that merely starts with the keyword is not an attempt.
+        assert_eq!(role("-- rolebased notes\nSELECT 1").unwrap(), None);
+    }
+
     fn matcher(id: &str) -> WorkspaceMatcher {
         WorkspaceMatcher { id: id.to_string(), include_forks: false }
     }

backend/windmill-trigger-postgres/src/handler.rs

@@ -21,11 +21,12 @@ use windmill_common::{
 use windmill_git_sync::DeployedObject;
 
 use windmill_api_auth::{check_scopes, ApiAuthed};
-use windmill_trigger::{Trigger, TriggerCrud, TriggerData};
+use windmill_trigger::{Trigger, TriggerCrud, TriggerData, TriggerMode};
 
 use super::{
     check_if_valid_publication_for_postgres_version, create_logical_replication_slot,
-    create_pg_publication, drop_publication, generate_random_string, get_default_pg_connection,
+    create_pg_publication, drop_publication, ensure_not_under_roles, generate_random_string,
+    get_default_pg_connection,
     mapper::{Mapper, MappingInfo},
     PostgresConfig, PostgresConfigRequest, PostgresPublicationReplication, PostgresTrigger,
     PublicationData, Relations, Slot, SlotList, TableToTrack, TemplateScript, TestPostgresConfig,
@@ -64,6 +65,29 @@ impl TriggerCrud for PostgresTrigger {
         DeployedObject::PostgresTrigger { path, parent_path }
     }
 
+    async fn validate_config(
+        &self,
+        db: &DB,
+        config: &Self::TriggerConfigRequest,
+        workspace_id: &str,
+    ) -> Result<()> {
+        ensure_not_under_roles(db, workspace_id, &config.postgres_resource_path).await
+    }
+
+    async fn authorize_set_trigger_mode(
+        &self,
+        _authed: &ApiAuthed,
+        tx: &mut PgConnection,
+        _workspace_id: &str,
+        _path: &str,
+        mode: &TriggerMode,
+    ) -> Result<()> {
+        if *mode != TriggerMode::Disabled {
+            windmill_common::datatable_roles::lock_datatable_streams(tx, false).await?;
+        }
+        Ok(())
+    }
+
     async fn create_trigger(
         &self,
         db: &DB,
@@ -72,6 +96,7 @@ impl TriggerCrud for PostgresTrigger {
         w_id: &str,
         trigger: TriggerData<Self::TriggerConfigRequest>,
     ) -> Result<()> {
+        windmill_common::datatable_roles::lock_datatable_streams(&mut *tx, false).await?;
         let resolved_edited_by = trigger.base.resolve_edited_by(authed);
         let resolved_permissioned_as = trigger.base.resolve_permissioned_as(authed);
         let Self::TriggerConfigRequest {
@@ -161,6 +186,7 @@ impl TriggerCrud for PostgresTrigger {
         path: &str,
         trigger: TriggerData<Self::TriggerConfigRequest>,
     ) -> Result<()> {
+        windmill_common::datatable_roles::lock_datatable_streams(&mut *tx, false).await?;
         let resolved_edited_by = trigger.base.resolve_edited_by(authed);
         let resolved_permissioned_as = trigger.base.resolve_permissioned_as(authed);
         let Self::TriggerConfigRequest {

backend/windmill-trigger-postgres/src/lib.rs

@@ -374,6 +374,35 @@ pub async fn get_raw_postgres_connection(
     Ok(client)
 }
 
+/// A replication stream reads every row of every table whatever the data table's roles grant, so
+/// the two don't mix: a data table under roles takes no triggers or captures, and roles cannot be
+/// turned on while one is enabled on it.
+///
+/// Authorization: checks nothing, and its refusal says whether `w_id`'s data table is under roles.
+/// Callers MUST have established that the caller may manage triggers in `w_id` first.
+pub(crate) async fn ensure_not_under_roles(
+    db: &DB,
+    w_id: &str,
+    postgres_resource_path: &str,
+) -> Result<()> {
+    let Some(datatable_name) = postgres_resource_path.strip_prefix("datatable://") else {
+        return Ok(());
+    };
+    if windmill_common::workspaces::resolve_governing_datatable(db, w_id, datatable_name)
+        .await?
+        .datatable
+        .permissions
+        .is_some()
+    {
+        return Err(Error::BadRequest(format!(
+            "Data table '{datatable_name}' is under roles, and a Postgres trigger or capture \
+             cannot read one: a replication stream sees every row whatever the roles grant. \
+             Turn its roles off to stream it."
+        )));
+    }
+    Ok(())
+}
+
 pub async fn resolve_postgres_resource(
     authed: &ApiAuthed,
     user_db: Option<UserDB>,
@@ -382,6 +411,7 @@ pub async fn resolve_postgres_resource(
     w_id: &str,
 ) -> Result<Postgres> {
     if let Some(datatable_name) = postgres_resource_path.strip_prefix("datatable://") {
+        ensure_not_under_roles(db, w_id, postgres_resource_path).await?;
         // Trigger connections (publication/slot management + logical replication) run
         // as the dedicated replication user on custom-instance databases.
         let resource_value =

backend/windmill-trigger-postgres/src/listener.rs

@@ -20,7 +20,8 @@ use windmill_common::{
 use windmill_trigger::{listener::ListeningTrigger, trigger_helpers::TriggerJobArgs, Listener};
 
 use super::{
-    drop_publication, get_default_pg_connection, get_raw_postgres_connection,
+    drop_publication, ensure_not_under_roles, get_default_pg_connection,
+    get_raw_postgres_connection,
     handler::drop_logical_replication_slot,
     relation::RelationConverter,
     replication_message::{
@@ -135,8 +136,8 @@ impl PostgresSimpleClient {
 /// Resolves the Postgres resource, validates that the configured publication and
 /// replication slot still exist, and opens a fresh logical replication stream.
 ///
-/// Returns `Error::BadConfig` when the publication or slot is missing (an
-/// unrecoverable misconfiguration). Any other error is treated as transient
+/// Returns `Error::BadConfig` when the publication or slot is missing, or the
+/// data table is under roles (unrecoverable misconfigurations). Any other error is treated as transient
 /// (connection refused, network interruption, ...) and is retried by the caller.
 /// The resource is re-resolved on every call so credential rotations are picked
 /// up across reconnections.
@@ -149,6 +150,14 @@ async fn connect_logical_replication_stream(
     let PostgresConfig { postgres_resource_path, publication_name, replication_slot_name, .. } =
         trigger_config;
 
+    // Retrying cannot lift roles, so this disables the trigger like a missing slot does.
+    ensure_not_under_roles(db, workspace_id, postgres_resource_path)
+        .await
+        .map_err(|e| match e {
+            Error::BadRequest(msg) => Error::BadConfig(msg),
+            e => e,
+        })?;
+
     let database = resolve_postgres_resource(
         authed,
         Some(UserDB::new(db.clone())),

backend/windmill-worker/src/agent_workers.rs

@@ -64,16 +64,25 @@ pub async fn get_ducklake_from_agent_http(
         .await
 }
 
+/// An agent worker authenticates as infrastructure, not as the job's user, so the job id travels
+/// with the request: the server reads the job's owner from it and evaluates the data table's
+/// tenants against them. A worker predating this sends neither, and the server fails it closed on
+/// a data table under roles.
 #[allow(dead_code)]
 pub async fn get_datatable_resource_from_agent_http(
     client: &HttpClient,
     name: &str,
     w_id: &str,
+    role: Option<&str>,
+    job_id: &uuid::Uuid,
 ) -> anyhow::Result<serde_json::Value> {
+    let role_query = role
+        .map(|r| format!("&role={}", urlencoding::encode(r)))
+        .unwrap_or_default();
     client
         .get(&format!(
-            "/api/w/{}/agent_workers/get_datatable_resource/{}",
-            w_id, &name
+            "/api/w/{}/agent_workers/get_datatable_resource/{}?job_id={}{}",
+            w_id, &name, job_id, role_query
         ))
         .await
 }

backend/windmill-worker/src/duckdb_executor.rs

@@ -13,8 +13,8 @@ use windmill_common::error::{to_anyhow, Error, Result};
 use windmill_common::utils::sanitize_string_from_password;
 use windmill_common::worker::{get_memory, to_raw_value, Connection, SqlResultCollectionStrategy};
 use windmill_common::workspaces::{
-    get_datatable_resource_from_db_unchecked, get_ducklake_from_db_unchecked,
-    strip_fork_reserved_attach_args, DucklakeCatalogResourceType,
+    get_datatable_resource_from_db, get_ducklake_from_db_unchecked,
+    strip_fork_reserved_attach_args, DatatableAccess, DucklakeCatalogResourceType,
 };
 use windmill_common::PgDatabase;
 use windmill_object_store::S3_PROXY_LAST_ERRORS_CACHE;
@@ -1494,13 +1494,9 @@ pub async fn do_duckdb(
                 .await?
                 {
                     probe_blocks.extend(q);
-                } else if let Some(q) = transform_attach_datatable(
-                    &query_block,
-                    conn,
-                    &mut hidden_passwords,
-                    &job.workspace_id,
-                )
-                .await?
+                } else if let Some(q) =
+                    transform_attach_datatable(&query_block, conn, &mut hidden_passwords, job)
+                        .await?
                 {
                     probe_blocks.extend(q);
                 } else {
@@ -1575,13 +1571,9 @@ pub async fn do_duckdb(
                 .await?
                 {
                     v.extend(ducklake_query);
-                } else if let Some(datatable_query) = transform_attach_datatable(
-                    &query_block,
-                    conn,
-                    &mut hidden_passwords,
-                    &job.workspace_id,
-                )
-                .await?
+                } else if let Some(datatable_query) =
+                    transform_attach_datatable(&query_block, conn, &mut hidden_passwords, job)
+                        .await?
                 {
                     v.extend(datatable_query);
                 } else {
@@ -2248,11 +2240,99 @@ fn parse_attach_db_resource<'a>(query: &'a str) -> Option<ParsedAttachDbResource
     None
 }
 
+/// The verification a DuckDB postgres attach keeps, as its libpq `sslmode` and `sslrootcert`.
+///
+/// Attaches have always turned verify-ca and verify-full into `require`, which resources rely on.
+/// A connection that explicitly refuses invalid certificates — the external instance cluster's —
+/// keeps its mode instead: under `require` its shared password would go to whichever server
+/// answers. DuckDB's libpq takes one root file, so it gets the system bundle plus the configured
+/// certificate.
+fn pg_attach_verification(res: &PgDatabase) -> Result<Option<(&str, std::path::PathBuf)>> {
+    let mode = match res.sslmode.as_deref() {
+        Some(mode @ ("verify-ca" | "verify-full")) if res.accept_invalid_certs == Some(false) => mode,
+        _ => return Ok(None),
+    };
+    let bundle = windmill_common::system_ca_bundle()
+        .map(std::fs::read_to_string)
+        .transpose()
+        .map_err(|e| Error::ExecutionErr(format!("Failed to read the system CA bundle: {e}")))?
+        .unwrap_or_default();
+    let pem = res.root_certificate_pem.as_deref().unwrap_or_default();
+    if bundle.is_empty() && pem.is_empty() {
+        return Err(Error::ExecutionErr(format!(
+            "sslmode {mode} needs a root certificate, and this worker has no system CA bundle"
+        )));
+    }
+    let roots = format!("{bundle}\n{pem}\n");
+    use sha2::Digest;
+    let dir = std::env::temp_dir().join("windmill-pg-roots");
+    let path = dir.join(format!(
+        "{}.pem",
+        hex::encode(&sha2::Sha256::digest(roots.as_bytes())[..8])
+    ));
+    let write_err = |e: std::io::Error| {
+        Error::ExecutionErr(format!("Failed to write root certificates: {e}"))
+    };
+    if path.is_file() {
+        // Marks it recently used, so pruning takes the others first.
+        let _ = std::fs::File::options()
+            .append(true)
+            .open(&path)
+            .and_then(|f| f.set_modified(std::time::SystemTime::now()));
+    } else {
+        std::fs::create_dir_all(&dir).map_err(write_err)?;
+        // Renamed into place: a job attaching concurrently must never read a half-written file.
+        let partial = path.with_extension(format!("{}.partial", Uuid::new_v4()));
+        std::fs::write(&partial, &roots)
+            .and_then(|()| std::fs::rename(&partial, &path))
+            .map_err(write_err)?;
+        prune_pg_roots(&dir, &path);
+    }
+    Ok(Some((mode, path)))
+}
+
+/// Root files outlive the job: a resource's certificate is workspace-controlled, so each distinct
+/// one would otherwise add a file forever. Keeps the most recently used ones.
+const PG_ROOTS_KEPT: usize = 32;
+
+fn prune_pg_roots(dir: &std::path::Path, keep: &std::path::Path) {
+    let Ok(entries) = std::fs::read_dir(dir) else {
+        return;
+    };
+    let mut files: Vec<(std::time::SystemTime, std::path::PathBuf)> = entries
+        .filter_map(|e| e.ok())
+        .map(|e| e.path())
+        .filter(|p| p.extension().is_some_and(|x| x == "pem") && p != keep)
+        .filter_map(|p| Some((std::fs::metadata(&p).ok()?.modified().ok()?, p)))
+        .collect();
+    if files.len() < PG_ROOTS_KEPT {
+        return;
+    }
+    files.sort();
+    for (_, p) in &files[..=files.len() - PG_ROOTS_KEPT] {
+        let _ = std::fs::remove_file(p);
+    }
+}
+
+fn pg_attach_uri(res: &PgDatabase) -> Result<String> {
+    let uri = res.to_uri();
+    let Some((mode, roots)) = pg_attach_verification(res)? else {
+        return Ok(uri);
+    };
+    let base = uri.strip_suffix("?sslmode=require").ok_or_else(|| {
+        Error::internal_err("unexpected sslmode in a postgres connection URI".to_string())
+    })?;
+    Ok(format!(
+        "{base}?sslmode={mode}&sslrootcert={}",
+        urlencoding::encode(&roots.to_string_lossy())
+    ))
+}
+
 fn format_attach_db_conn_str(db_resource: Value, db_type: &str) -> Result<String> {
     let s = match db_type.to_lowercase().as_str() {
         "postgres" | "postgresql" => {
             let res: PgDatabase = serde_json::from_value(db_resource)?;
-            res.to_uri()
+            pg_attach_uri(&res)?
         }
         #[cfg(feature = "mysql")]
         "mysql" => {
@@ -2399,7 +2479,9 @@ async fn transform_attach_ducklake(
         format!(", {}", user_extra_args)
     };
     let db_type = match ducklake.catalog.resource_type {
-        DucklakeCatalogResourceType::Instance => "postgres",
+        DucklakeCatalogResourceType::Instance | DucklakeCatalogResourceType::ExternalInstance => {
+            "postgres"
+        }
         _ => ducklake.catalog.resource_type.as_ref(),
     };
 
@@ -2515,7 +2597,8 @@ fn fork_defer_statements(
             hidden_passwords.lock().unwrap().push(pwd.to_string());
         }
         let db_type = match a.catalog.resource_type {
-            DucklakeCatalogResourceType::Instance => "postgres",
+            DucklakeCatalogResourceType::Instance
+            | DucklakeCatalogResourceType::ExternalInstance => "postgres",
             _ => a.catalog.resource_type.as_ref(),
         };
         stmts.push(get_attach_db_install_str(db_type)?.to_string());
@@ -2609,33 +2692,79 @@ fn fork_defer_statements(
     Ok(stmts)
 }
 
+struct AttachedDatatable<'a> {
+    /// The data table reference, query string included; a bare `datatable` is `main`.
+    reference: String,
+    alias: &'a str,
+}
+
+/// `ATTACH 'datatable[://<name>][?role=<role>]' AS <alias>`. A bare `datatable` names the default
+/// data table, so the role query string has to be accepted with and without an explicit name. The
+/// reference is split only once the workspace can be read, because a stored name may contain `?`.
+fn parse_attach_datatable(query: &str) -> Option<AttachedDatatable<'_>> {
+    lazy_static::lazy_static! {
+        static ref RE: regex::Regex = regex::Regex::new(
+            r"(?i)ATTACH\s*'datatable(://[^':]+|\?[^':]*)?'\s*AS\s+([^ ;]+)"
+        ).unwrap();
+    }
+    let cap = RE.captures(query)?;
+    let reference = match cap.get(1).map(|m| m.as_str()) {
+        Some(named) if named.starts_with("://") => named[3..].to_string(),
+        Some(query) => format!("main{query}"),
+        None => "main".to_string(),
+    };
+    let alias = cap.get(2).map(|m| m.as_str()).unwrap_or("");
+    Some(AttachedDatatable { reference, alias })
+}
+
 async fn transform_attach_datatable(
     query: &str,
     conn: &Connection,
     hidden_passwords: &mut Arc<Mutex<Vec<String>>>,
-    w_id: &str,
+    job: &MiniPulledJob,
 ) -> Result<Option<Vec<String>>> {
-    lazy_static::lazy_static! {
-        static ref RE: regex::Regex = regex::Regex::new(r"(?i)ATTACH\s*'datatable(://[^':]+)?'\s*AS\s+([^ ;]+)").unwrap();
-    }
-    let Some(cap) = RE.captures(query) else {
+    let Some(attached) = parse_attach_datatable(query) else {
         return Ok(None);
     };
-    let name = cap.get(1).map(|m| &m.as_str()[3..]).unwrap_or("main");
-    let alias_name = cap.get(2).map(|m| m.as_str()).unwrap_or("");
 
+    // A query string that does not parse is refused rather than dropped: attaching under the
+    // default role when the statement asked for another one is the failure this guards.
     let db_resource = match conn {
         Connection::Http(client) => {
-            get_datatable_resource_from_agent_http(client, name, w_id).await?
+            let (name, role) =
+                windmill_common::workspaces::parse_datatable_ref(&attached.reference)?;
+            get_datatable_resource_from_agent_http(client, name, &job.workspace_id, role, &job.id)
+                .await?
+        }
+        Connection::Sql(db) => {
+            let (name, role) = windmill_common::workspaces::parse_datatable_ref_for(
+                db,
+                &job.workspace_id,
+                &attached.reference,
+            )
+            .await?;
+            get_datatable_resource_from_db(
+                db,
+                &job.workspace_id,
+                &name,
+                role.as_deref(),
+                DatatableAccess::PermissionedAs {
+                    permissioned_as: &job.permissioned_as,
+                    email: &job.permissioned_as_email,
+                },
+            )
+            .await?
         }
-        Connection::Sql(db) => get_datatable_resource_from_db_unchecked(db, w_id, name).await?,
     };
 
     if let Some(pwd) = db_resource.get("password").and_then(|p| p.as_str()) {
         hidden_passwords.lock().unwrap().push(pwd.to_string());
     }
 
-    Ok(Some(pg_secret_attach_statements(db_resource, alias_name)?))
+    Ok(Some(pg_secret_attach_statements(
+        db_resource,
+        attached.alias,
+    )?))
 }
 
 // Secret names must be plain identifiers; the hash keeps two aliases distinct even
@@ -2662,10 +2791,21 @@ fn pg_secret_attach_statements(db_resource: Value, alias_name: &str) -> Result<V
     let esc = |s: &str| s.replace('\'', "''");
     // The postgres secret type has no sslmode parameter, so it goes in the ATTACH
     // string; only the libpq values PgDatabase::to_uri collapses to are forwarded.
-    let sslmode = match res.sslmode.as_deref() {
-        Some("disable") => "disable",
-        Some("require") | Some("verify-ca") | Some("verify-full") => "require",
-        _ => "prefer",
+    let sslmode = match pg_attach_verification(&res)? {
+        // A libpq keyword/value string: the path is quoted for libpq, then for the DuckDB literal.
+        Some((mode, roots)) => format!(
+            "{mode} sslrootcert=''{}''",
+            roots
+                .to_string_lossy()
+                .replace('\\', "\\\\")
+                .replace('\'', "\\''")
+        ),
+        None => match res.sslmode.as_deref() {
+            Some("disable") => "disable",
+            Some("require") | Some("verify-ca") | Some("verify-full") => "require",
+            _ => "prefer",
+        }
+        .to_string(),
     };
     let secret_name = datatable_secret_name(alias_name);
     Ok(vec![
@@ -2680,6 +2820,11 @@ fn pg_secret_attach_statements(db_resource: Value, alias_name: &str) -> Result<V
             esc(res.password.as_deref().unwrap_or("")),
         ),
         format!("ATTACH 'sslmode={sslmode}' AS {alias_name} (TYPE postgres, SECRET {secret_name});"),
+        // The attachment keeps its own resolved connection string, so the secret is dead weight
+        // once attached — and a live one is a credential the script's own statements can name: an
+        // `ATTACH 'dbname=<other>' (TYPE postgres, SECRET …)` would reach a database nobody
+        // authorized this job for, as this role.
+        format!("DROP TEMPORARY SECRET {secret_name};"),
     ])
 }
 
@@ -2753,6 +2898,85 @@ pub struct Arg {
 mod tests {
     use super::*;
 
+    #[test]
+    fn pg_attach_keeps_verification_only_when_required() {
+        let pg = |sslmode: &str, accept_invalid_certs: Option<bool>| PgDatabase {
+            host: "db.internal".to_string(),
+            user: Some("custom_instance_user".to_string()),
+            password: Some("pw".to_string()),
+            port: None,
+            sslmode: Some(sslmode.to_string()),
+            dbname: "dt".to_string(),
+            root_certificate_pem: Some("-----BEGIN CERTIFICATE-----test".to_string()),
+            accept_invalid_certs,
+            use_iam_auth: None,
+            region: None,
+        };
+        let uri = pg_attach_uri(&pg("verify-full", Some(false))).unwrap();
+        assert!(uri.contains("?sslmode=verify-full&sslrootcert="), "{uri}");
+        let root = urlencoding::decode(uri.split("sslrootcert=").nth(1).unwrap()).unwrap();
+        let roots = std::fs::read_to_string(root.as_ref()).unwrap();
+        for i in 0..(PG_ROOTS_KEPT + 5) {
+            let mut other = pg("verify-full", Some(false));
+            other.root_certificate_pem = Some(format!("-----BEGIN CERTIFICATE-----{i}"));
+            pg_attach_uri(&other).unwrap();
+        }
+        let kept = std::fs::read_dir(std::env::temp_dir().join("windmill-pg-roots"))
+            .unwrap()
+            .filter(|e| e.as_ref().unwrap().path().extension().is_some_and(|x| x == "pem"))
+            .count();
+        assert!(kept <= PG_ROOTS_KEPT, "{kept} root files kept");
+        assert!(roots.contains("-----BEGIN CERTIFICATE-----test"));
+        let external = serde_json::to_value(pg("verify-full", Some(false))).unwrap();
+        let attach = &pg_secret_attach_statements(external, "dt").unwrap()[3];
+        assert!(
+            attach.starts_with(&format!("ATTACH 'sslmode=verify-full sslrootcert=''{}''", root)),
+            "{attach}"
+        );
+        // A resource that never opted in keeps the historical downgrade.
+        assert!(pg_attach_uri(&pg("verify-full", None)).unwrap().ends_with("?sslmode=require"));
+        assert!(pg_attach_uri(&pg("require", Some(false))).unwrap().ends_with("?sslmode=require"));
+    }
+
+    #[test]
+    fn attach_datatable_parses_name_and_role() {
+        let reference_of = |q: &str| parse_attach_datatable(q).unwrap().reference;
+        let named =
+            parse_attach_datatable("ATTACH 'datatable://sales?role=analytics' AS dt").unwrap();
+        assert_eq!(
+            (named.reference.as_str(), named.alias),
+            ("sales?role=analytics", "dt")
+        );
+        // A bare `datatable` is the default one, and still takes a role.
+        assert_eq!(
+            reference_of("ATTACH 'datatable?role=analytics' AS dt"),
+            "main?role=analytics"
+        );
+        assert_eq!(reference_of("ATTACH 'datatable://sales' AS dt"), "sales");
+        assert_eq!(reference_of("ATTACH 'datatable' AS dt"), "main");
+        assert!(parse_attach_datatable("SELECT 1").is_none());
+        // A stored name can contain `?`, so that is left to the workspace lookup to split.
+        assert_eq!(reference_of("ATTACH 'datatable://a?b' AS dt"), "a?b");
+
+        // The key matches case-insensitively, as the `-- role` annotation does, and a query string
+        // that does not parse is refused rather than attached under the default role.
+        let parse = |q: &str| {
+            windmill_common::workspaces::parse_datatable_ref(&reference_of(q))
+                .map(|(name, role)| (name.to_string(), role.map(str::to_string)))
+        };
+        assert_eq!(
+            parse("ATTACH 'datatable://sales?Role=analytics' AS dt").unwrap(),
+            ("sales".to_string(), Some("analytics".to_string()))
+        );
+        for malformed in [
+            "ATTACH 'datatable://sales?role=' AS dt",
+            "ATTACH 'datatable://sales?role=an;alytics' AS dt",
+            "ATTACH 'datatable://sales?x=1&role=analytics' AS dt",
+        ] {
+            assert!(parse(malformed).is_err(), "silently ignored: {malformed}");
+        }
+    }
+
     #[test]
     fn decode_ffi_error_unescapes_multiline_and_strips_quotes() {
         // Mirror the FFI: JSON-encode the raw DuckDB message, prefix "ERROR ".
@@ -3868,6 +4092,8 @@ mod tests {
             stmts[3],
             format!("ATTACH 'sslmode=require' AS dt (TYPE postgres, SECRET {secret_name});")
         );
+        assert_eq!(stmts[4], format!("DROP TEMPORARY SECRET {secret_name};"));
+        assert_eq!(stmts.len(), 5);
     }
 
     #[test]

backend/windmill-worker/src/pg_executor.rs

@@ -26,9 +26,11 @@ use windmill_common::azure_workload_identity::WORKLOAD_IDENTITY_PASSWORD;
 use windmill_common::error::to_anyhow;
 use windmill_common::error::{self, Error};
 use windmill_common::worker::{
-    to_raw_value, Connection, SqlResultCollectionStrategy, CLOUD_HOSTED,
+    to_raw_value, Connection, SqlAnnotations, SqlResultCollectionStrategy, CLOUD_HOSTED,
+};
+use windmill_common::workspaces::{
+    get_datatable_resource_from_db, parse_datatable_ref, parse_datatable_ref_for, DatatableAccess,
 };
-use windmill_common::workspaces::get_datatable_resource_from_db_unchecked;
 use windmill_common::{PgDatabase, PrepareQueryColumnInfo, PrepareQueryResult, DB};
 use windmill_parser::{Arg, Typ};
 use windmill_parser_sql::{
@@ -680,15 +682,36 @@ pub async fn do_postgresql(
     } else {
         match pg_args.get("database").cloned() {
             Some(Value::String(db_str)) if db_str.starts_with("datatable://") => {
-                let db_str = db_str.trim_start_matches("datatable://");
+                let reference = db_str.trim_start_matches("datatable://");
+                // The annotation wins: a generated query can carry a `?role=` in the reference it
+                // was handed, but only the script's author writes the leading comment block.
+                let annotated = SqlAnnotations::datatable_role(&query)?;
                 Some(match conn {
                     Connection::Http(client) => {
-                        get_datatable_resource_from_agent_http(client, &db_str, &job.workspace_id)
-                            .await?
+                        let (name, uri_role) = parse_datatable_ref(reference)?;
+                        get_datatable_resource_from_agent_http(
+                            client,
+                            name,
+                            &job.workspace_id,
+                            annotated.as_deref().or(uri_role),
+                            &job.id,
+                        )
+                        .await?
                     }
                     Connection::Sql(db) => {
-                        get_datatable_resource_from_db_unchecked(db, &job.workspace_id, &db_str)
-                            .await?
+                        let (name, uri_role) =
+                            parse_datatable_ref_for(db, &job.workspace_id, reference).await?;
+                        get_datatable_resource_from_db(
+                            db,
+                            &job.workspace_id,
+                            &name,
+                            annotated.as_deref().or(uri_role.as_deref()),
+                            DatatableAccess::PermissionedAs {
+                                permissioned_as: &job.permissioned_as,
+                                email: &job.permissioned_as_email,
+                            },
+                        )
+                        .await?
                     }
                 })
             }

cli/src/commands/app/raw_apps.ts

@@ -55,6 +55,8 @@ export interface AppFile {
     tables?: string[];
     datatable?: string;
     schema?: string;
+    /** The role the app uses each data table through, by data table name. */
+    roles?: Record<string, string>;
   };
   // Mirrors granular ACLs on the raw_app path. Synced via /acls/* by
   // applyExtraPermsDiff — never through update_app_raw — so a perm-only

cli/src/commands/datatable/datatable.ts

@@ -111,6 +111,8 @@ const migrateCommand = new Command()
   )
   .action(migrateDown as any);
 
+type DataTableResourceType = "postgresql" | "instance" | "external_instance";
+
 async function create(
   opts: GlobalOptions & { resource?: string; force?: boolean },
   name?: string,
@@ -139,12 +141,12 @@ async function create(
 
   const datatables: Record<
     string,
-    { database: { resource_type: "postgresql" | "instance"; resource_path?: string } }
+    { database: { resource_type: DataTableResourceType; resource_path?: string } }
   > = {};
   for (const d of existing) {
     datatables[d.name] = {
       database: {
-        resource_type: d.resource_type as "postgresql" | "instance",
+        resource_type: d.resource_type as DataTableResourceType,
         resource_path: d.resource_path ?? undefined,
       },
     };

cli/src/core/settings.ts

@@ -393,10 +393,17 @@ export async function pushWorkspaceSettings(
 
   if (!deepEqual(localSettings.datatable, settings.datatable)) {
     log.debug(`Updating datatable config...`);
-    await wmill.editDataTableConfig({
+    const { stranded_references } = await wmill.editDataTableConfig({
       workspace,
       requestBody: { settings: localSettings.datatable ?? { datatables: {} } },
     });
+    if (stranded_references?.length) {
+      log.warn(
+        `Removed data tables governed data tables in other workspaces, which no longer resolve: ${stranded_references
+          .map((r) => `${r.workspace_id}/${r.datatable}`)
+          .join(", ")}. A superadmin can point them somewhere else.`,
+      );
+    }
   }
 
   if (localSettings.slack_command_script != settings.slack_command_script) {

cli/src/guidance/skills.gen.ts

@@ -1110,6 +1110,8 @@ parseS3Object(s3Object: S3Object): S3ObjectRecord
 /**
  * Create a SQL template function for PostgreSQL/datatable queries
  * @param name - Database/datatable name (default: "main")
+ * @param opts.role - Connect as this data table role instead of the data table's default one.
+ *   Only meaningful on a data table under roles, and only for a role you are a tenant of.
  * @returns SQL template function for building parameterized queries
  * @example
  * let sql = wmill.datatable()
@@ -1119,8 +1121,11 @@ parseS3Object(s3Object: S3Object): S3ObjectRecord
  *   SELECT * FROM friends
  *     WHERE name = \${name} AND age = \${age}::int
  * \`.fetch()
+ * @example
+ * // Read through a restricted role
+ * let sql = wmill.datatable("main", { role: "analytics" })
  */
-datatable(name: string = "main"): DatatableSqlTemplateFunction
+datatable(name: string = "main", opts?: DatatableOptions): DatatableSqlTemplateFunction
 
 /**
  * Create a SQL template function for DuckDB/ducklake queries
@@ -1901,6 +1906,8 @@ parseS3Object(s3Object: S3Object): S3ObjectRecord
 /**
  * Create a SQL template function for PostgreSQL/datatable queries
  * @param name - Database/datatable name (default: "main")
+ * @param opts.role - Connect as this data table role instead of the data table's default one.
+ *   Only meaningful on a data table under roles, and only for a role you are a tenant of.
  * @returns SQL template function for building parameterized queries
  * @example
  * let sql = wmill.datatable()
@@ -1910,8 +1917,11 @@ parseS3Object(s3Object: S3Object): S3ObjectRecord
  *   SELECT * FROM friends
  *     WHERE name = \${name} AND age = \${age}::int
  * \`.fetch()
+ * @example
+ * // Read through a restricted role
+ * let sql = wmill.datatable("main", { role: "analytics" })
  */
-datatable(name: string = "main"): DatatableSqlTemplateFunction
+datatable(name: string = "main", opts?: DatatableOptions): DatatableSqlTemplateFunction
 
 /**
  * Create a SQL template function for DuckDB/ducklake queries
@@ -2786,6 +2796,8 @@ parseS3Object(s3Object: S3Object): S3ObjectRecord
 /**
  * Create a SQL template function for PostgreSQL/datatable queries
  * @param name - Database/datatable name (default: "main")
+ * @param opts.role - Connect as this data table role instead of the data table's default one.
+ *   Only meaningful on a data table under roles, and only for a role you are a tenant of.
  * @returns SQL template function for building parameterized queries
  * @example
  * let sql = wmill.datatable()
@@ -2795,8 +2807,11 @@ parseS3Object(s3Object: S3Object): S3ObjectRecord
  *   SELECT * FROM friends
  *     WHERE name = \${name} AND age = \${age}::int
  * \`.fetch()
+ * @example
+ * // Read through a restricted role
+ * let sql = wmill.datatable("main", { role: "analytics" })
  */
-datatable(name: string = "main"): DatatableSqlTemplateFunction
+datatable(name: string = "main", opts?: DatatableOptions): DatatableSqlTemplateFunction
 
 /**
  * Create a SQL template function for DuckDB/ducklake queries
@@ -4405,10 +4420,13 @@ def send_teams_message(conversation_id: str, text: str, success: bool = True, ca
 # 
 # Args:
 #     name: Database name (default: "main")
+#     role: Connect as this data table role instead of the data table's default one.
+#         Only meaningful on a data table under roles, and only for a role you are a
+#         tenant of.
 # 
 # Returns:
 #     DataTableClient instance
-def datatable(name: str = 'main')
+def datatable(name: str = 'main', *, role: Optional[str] = None)
 
 # Get a DuckLake client for DuckDB queries.
 # 
@@ -4626,7 +4644,7 @@ def parse_sql_client_name(name: str) -> tuple[str, Optional[str]]
 # 
 #     @task(retry={"attempts": 3, "delay": 30, "multiplier": 2})
 #     async def call_api(payload: dict): ...
-def task(_func = None, path: Optional[str] = None, tag: Optional[str] = None, timeout: Optional[int] = None, cache_ttl: Optional[int] = None, priority: Optional[int] = None, concurrency_limit: Optional[int] = None, concurrency_key: Optional[str] = None, concurrency_time_window_s: Optional[int] = None, retry: Optional[dict] = None)
+def task(_func = None, *, path: Optional[str] = None, tag: Optional[str] = None, timeout: Optional[int] = None, cache_ttl: Optional[int] = None, priority: Optional[int] = None, concurrency_limit: Optional[int] = None, concurrency_key: Optional[str] = None, concurrency_time_window_s: Optional[int] = None, retry: Optional[dict] = None)
 
 # Create a task that dispatches to a separate Windmill script.
 # 
@@ -4639,7 +4657,7 @@ def task(_func = None, path: Optional[str] = None, tag: Optional[str] = None, ti
 #     @workflow
 #     async def main():
 #         data = await extract(url="https://...")
-def task_script(path: str, timeout: Optional[int] = None, tag: Optional[str] = None, cache_ttl: Optional[int] = None, priority: Optional[int] = None, concurrency_limit: Optional[int] = None, concurrency_key: Optional[str] = None, concurrency_time_window_s: Optional[int] = None, retry: Optional[dict] = None)
+def task_script(path: str, *, timeout: Optional[int] = None, tag: Optional[str] = None, cache_ttl: Optional[int] = None, priority: Optional[int] = None, concurrency_limit: Optional[int] = None, concurrency_key: Optional[str] = None, concurrency_time_window_s: Optional[int] = None, retry: Optional[dict] = None)
 
 # Create a task that dispatches to a separate Windmill flow.
 # 
@@ -4652,7 +4670,7 @@ def task_script(path: str, timeout: Optional[int] = None, tag: Optional[str] = N
 #     @workflow
 #     async def main():
 #         result = await pipeline(input=data)
-def task_flow(path: str, timeout: Optional[int] = None, tag: Optional[str] = None, cache_ttl: Optional[int] = None, priority: Optional[int] = None, concurrency_limit: Optional[int] = None, concurrency_key: Optional[str] = None, concurrency_time_window_s: Optional[int] = None, retry: Optional[dict] = None)
+def task_flow(path: str, *, timeout: Optional[int] = None, tag: Optional[str] = None, cache_ttl: Optional[int] = None, priority: Optional[int] = None, concurrency_limit: Optional[int] = None, concurrency_key: Optional[str] = None, concurrency_time_window_s: Optional[int] = None, retry: Optional[dict] = None)
 
 # Decorator marking an async function as a workflow-as-code entry point.
 # 
@@ -4717,7 +4735,7 @@ async def wait_for_approval(timeout: int = 1800, form: dict | None = None, self_
 #         ...
 # 
 #     results = await parallel(items, process, concurrency=5)
-async def parallel(items, fn, concurrency: Optional[int] = None)
+async def parallel(items, fn, *, concurrency: Optional[int] = None)
 
 # Commit Kafka offsets for a trigger with auto_commit disabled.
 # 
@@ -5808,6 +5826,8 @@ data:
   tables:
     - main/users            # Table in public schema
     - main/app_schema:items # Table in specific schema
+  roles:                    # Optional: the role the app uses each datatable through
+    main: analyst
 \`\`\`
 
 **Table reference formats:**
@@ -5815,6 +5835,8 @@ data:
 - \`<datatable>/<table>\` — Specific table in public schema
 - \`<datatable>/<schema>:<table>\` — Table in specific schema
 
+**Roles:** when a datatable is under roles, its queries run as a role, which only reaches what it was granted. \`roles\` records the role the app uses each datatable through; the app's code must pass the same role: \`wmill.datatable('main', { role: 'analyst' })\` in TypeScript, \`wmill.datatable('main', role='analyst')\` in Python. A datatable without an entry is used as its default role.
+
 ## SQL Migrations (sql_to_apply/)
 
 The \`sql_to_apply/\` folder is for creating/modifying database tables during development.

docs/external-instance-datatables.md

@@ -0,0 +1,88 @@
+# External instance data tables
+
+A data table is backed by one of three things: a Postgres resource a workspace brings
+(`postgresql`), a database on Windmill's own cluster (`instance`), or a database on a separate
+cluster Windmill administers (`external_instance`, Enterprise Edition). The third is what this
+document covers; Ducklake catalogs take the same three shapes.
+
+Windmill administers the external cluster the way it administers its own: it creates and drops
+databases there, owns `custom_instance_user` and `custom_instance_replication_user`, and creates
+the data table roles of that cluster. It logs in as the admin in the `external_instance_pg`
+instance setting, and keeps what it generates in the hidden `external_instance_pg_state` setting.
+
+## Code
+
+| Where | What |
+|---|---|
+| `windmill-common/src/external_instance_pg.rs` | Setting, state, usage accounting, the lifecycle lock, the OSS forwarders |
+| `windmill-common/src/external_instance_pg_ee.rs` | Setup, database create and drop, the admin connection |
+| `windmill-common/src/datatable_roles.rs` | Per-cluster role catalogs (`DatatableRoleCluster`) |
+| `windmill-common/src/workspaces.rs` | Resolution (`resolve_datatable_connection_unchecked`), `managed_database_uses` |
+| `windmill-api-settings/src/lib.rs` | `/settings/external_instance_pg/*`, `/settings/datatable_roles` |
+
+## What holds it together
+
+- **One lifecycle lock.** `lock_external_instance_pg_state` serializes everything that changes
+  which databases exist on the cluster or which entries name them: setup, create, drop, data table
+  and Ducklake saves, external role DDL, and writes to the setting itself. Anything reading the
+  configuration to reach the cluster reads it under that lock, so a database is never created on
+  one cluster and registered while the setting names another.
+- **Windmill only touches what it made.** Databases it creates carry a comment, and a drop
+  requires it. The two managed roles and every data table role carry their own comment, and setup
+  refuses a `custom_instance_user` without it rather than resetting the password of someone else's
+  role.
+- **Creation needs a successful setup.** `set_up_for` records the `host:port` the last successful
+  setup converged. Creating a database on a cluster that setup has not succeeded on is refused.
+- **Nothing is dropped from under a user.** `managed_database_uses` lists every data table naming
+  a database, every fork pointing at those, every Ducklake catalog on it, and every fork Ducklake
+  metadata schema still to be dropped. Fork cleanup exempts exactly the entry it is cleaning up.
+- **Fork copies belong to a workspace.** `wm_fork_*` is a name, not an authorization: every
+  database of a cluster answers to the same `custom_instance_user`. The registry records the
+  workspace a copy was created for, and a member can only import into or fork onto a copy of their
+  own workspace.
+- **Roles are per cluster.** `datatable_role.cluster` splits the catalog, so the same role name can
+  exist on both clusters. Role names are unique per cluster, as they are in Postgres.
+
+## Running one locally
+
+```bash
+docker run -d --name wm-external-pg -e POSTGRES_PASSWORD=external -p 5497:5432 postgres:18 \
+  -c wal_level=logical
+psql "postgresql://postgres:external@127.0.0.1:5497/postgres" \
+  -c "CREATE ROLE wm_admin LOGIN PASSWORD 'adminpw' CREATEDB CREATEROLE REPLICATION"
+```
+
+A non-superuser admin with `CREATEDB` and `CREATEROLE` is the realistic case: managed Postgres
+gives nothing more. `REPLICATION` is only needed for Postgres triggers on external data tables.
+
+Then, as superadmin (`$T` is a token):
+
+```bash
+api=http://localhost:8000/api
+curl -s -X POST $api/settings/global/external_instance_pg -H "Authorization: Bearer $T" \
+  -H 'Content-Type: application/json' \
+  --data '{"value":{"host":"127.0.0.1","port":5497,"user":"wm_admin","password":"adminpw","sslmode":"disable"}}'
+curl -s -X POST $api/settings/external_instance_pg/setup -H "Authorization: Bearer $T" \
+  -H 'Content-Type: application/json' --data '{}'          # report per step
+curl -s -X POST $api/settings/external_instance_pg/databases/dt_demo -H "Authorization: Bearer $T" \
+  -H 'Content-Type: application/json' --data '{}'
+curl -s -X POST $api/w/admins/workspaces/edit_datatable_config -H "Authorization: Bearer $T" \
+  -H 'Content-Type: application/json' \
+  --data '{"settings":{"datatables":{"demo":{"database":{"resource_type":"external_instance","resource_path":"dt_demo"}}}}}'
+```
+
+`sslmode` defaults to `verify-full`; `disable` is for a local container only. With `verify-full`
+against a server with a private CA, put the CA in `root_certificate_pem` — `pg_dump`, `psql` and
+DuckDB attaches all verify against the system trust store plus that certificate.
+
+Jobs then reach it as any data table: `ATTACH 'datatable://demo' AS d` from DuckDB, or
+`datatable://demo` as the database of a PostgreSQL script, with `-- role <name>` to connect as a
+data table role of that cluster.
+
+Worth knowing while testing:
+
+- A worker needs the `postgresql` and `duckdb` tags for those jobs
+  (`update config set config = jsonb_set(config, '{worker_tags}', …) where name = 'worker__default'`).
+- DuckDB jobs load `libwindmill_duckdb_ffi_internal.so` by name, so a binary built into its own
+  `CARGO_TARGET_DIR` needs that library on `LD_LIBRARY_PATH`.
+- Setup holds the lifecycle lock for its whole run, so a settings save during it waits.

flake.nix

@@ -65,7 +65,10 @@
 
           # Misc
           libtool
-          postgresql
+          # Must not trail the server the dev database runs (postgres:18): pg_dump refuses a
+          # server newer than itself by a major version, which takes out every data table
+          # export, clone and fork-with-data.
+          postgresql_18
 
           # Build tooling
           pkg-config

frontend/src/lib/components/DBManagerContent.svelte

@@ -1,16 +1,21 @@
 <script lang="ts">
 	import { dbSchemas, workspaceStore, type DBSchema } from '$lib/stores'
+	import type { DataTableTables } from '$lib/gen'
 	import { sortArray } from '$lib/utils'
 	import { Loader2, RefreshCcw } from 'lucide-svelte'
 	import Alert from './common/alert/Alert.svelte'
 	import Button from './common/button/Button.svelte'
-	import { dbSupportsSchemas } from './apps/components/display/dbtable/utils'
+	import {
+		dbSupportsSchemas,
+		getLanguageByResourceType
+	} from './apps/components/display/dbtable/utils'
 	import DbManager from './DBManager.svelte'
 	import DbWorkerTagPicker from './DbWorkerTagPicker.svelte'
 	import MissingWorkerTagAlert from './jobs/MissingWorkerTagAlert.svelte'
 	import {
 		dbSchemaOpsWithPreviewScripts,
 		dbTableOpsWithPreviewScripts,
+		getDatabaseArg,
 		getDbType,
 		getDefaultDbTag,
 		getDucklakeSchema
@@ -18,11 +23,11 @@
 	import { Pane, Splitpanes } from 'svelte-splitpanes'
 	import SqlRepl from './SqlRepl.svelte'
 	import SimpleAgTable from './SimpleAgTable.svelte'
-	import { type Snippet } from 'svelte'
-	import type { DbInput } from './dbTypes'
+	import type { DatatableRowAction, DbInput } from './dbTypes'
+	import { schemaCacheKey } from './dbSchemaCache'
 	import { getDbSchemas, loadAllTablesMetaData } from './apps/components/display/dbtable/metadata'
 
-	import type { SelectedTable } from './DBManager.svelte'
+	import type { PendingRowAction, SelectedTable } from './DBManager.svelte'
 	import { getDbFeatures } from './apps/components/display/dbtable/dbFeatures'
 	import { resource } from 'runed'
 	import ConfirmationModal from './common/confirmationModal/ConfirmationModal.svelte'
@@ -36,7 +41,15 @@
 		hasReplResult?: boolean
 		selectedSchemaKey?: string | undefined
 		selectedTableKey?: string | undefined
-		dbSelector?: Snippet<[]>
+		/** Every data table with its schemas and tables, for the left-pane tree. Undefined when
+		 * the manager is not on a data table, which drops the tree's top level. */
+		datatableTree?: DataTableTables[]
+		datatableTreeLoading?: boolean
+		onSelectDatatable?: (datatable: string) => void
+		onSelectRole?: (datatable: string, role: string) => void
+		pendingAction?: PendingRowAction | undefined
+		onDatatableAction?: (datatable: string, action: DatatableRowAction) => void
+		canManageDatatable?: boolean
 		/** Enable multi-select mode with checkboxes in sidebar */
 		multiSelectMode?: boolean
 		/** Selected tables in multi-select mode */
@@ -59,7 +72,13 @@
 		hasReplResult = $bindable(false),
 		selectedSchemaKey = $bindable(undefined),
 		selectedTableKey = $bindable(undefined),
-		dbSelector,
+		datatableTree,
+		datatableTreeLoading,
+		onSelectDatatable,
+		onSelectRole,
+		pendingAction = $bindable(),
+		onDatatableAction,
+		canManageDatatable,
 		multiSelectMode = false,
 		selectedTables = $bindable([]),
 		disabledTables = [],
@@ -70,33 +89,25 @@
 
 	let ws = $derived(workspace ?? $workspaceStore)
 
-	let dbSchema: DBSchema | undefined = $derived(input && $dbSchemas[schemaCacheKey(input)])
+	let dbSchema: DBSchema | undefined = $derived(input && $dbSchemas[schemaCacheKey(ws, input)])
 
 	const outOfOrderModal = createAsyncConfirmationModal()
 
-	function getDbSchemasPath(input: DbInput): string {
-		switch (input.type) {
-			case 'database':
-				return input.resourcePath
-			case 'ducklake':
-				return 'ducklake://' + input.ducklake
-		}
-	}
-
-	// Scope the shared `dbSchemas` cache by the acting workspace: a datatable of
-	// the same name can exist in both the nav and the acting workspace, so the
-	// bare resource path alone would let one workspace's schema be reused for the
-	// other while DB operations target the acting one.
-	function schemaCacheKey(input: DbInput): string {
-		return `${ws}:${getDbSchemasPath(input)}`
-	}
-
 	// Reported in place of the loading spinner: both queries run as jobs, so
 	// anything from a bad connection to a tag no worker serves surfaces here
 	// instead of leaving the manager spinning with no explanation. Each query
 	// owns its slot so neither can clear the other's error on a refetch.
 	let schemaError = $state<string | undefined>(undefined)
 	let colDefsError = $state<string | undefined>(undefined)
+	function emptySchemaFor(db: DbInput): DBSchema {
+		return {
+			lang: db.type === 'ducklake' ? 'ducklake' : getLanguageByResourceType(db.resourceType),
+			schema: {},
+			publicOnly: undefined,
+			stringified: ''
+		} as DBSchema
+	}
+
 	let loadError = $derived(
 		schemaError
 			? { title: 'Could not load the database schema', message: schemaError }
@@ -136,14 +147,23 @@
 			const run = ++schemaRun
 			schemaError = undefined
 			if (!input) return
-			const dbSchemasPath = schemaCacheKey(input)
+			const dbSchemasPath = schemaCacheKey(ws, input)
 			if (input.type == 'database') {
+				let connection = input.resourcePath
+				try {
+					// The role'd reference, validated: an invalid role fails here rather than
+					// reading the schema as the data table's default role.
+					if (connection.startsWith('datatable://')) connection = getDatabaseArg(input).database!
+				} catch (e) {
+					schemaError = (e as Error)?.message ?? String(e)
+					return
+				}
 				// Reported through a local, not `schemaError` directly, so a superseded
 				// run's callback can't fail a load that already succeeded.
 				let queryError: string | undefined
 				const schema = await getDbSchemas(
 					input.resourceType,
-					input.resourcePath,
+					connection,
 					ws,
 					(message: string) => (queryError = message),
 					{ customTag: workerTag }
@@ -223,17 +243,23 @@
 	}}
 />
 
-<!-- The error branch comes first on purpose: `dbSchema` is read from a cache that
-	survives a failed refetch, so ordering it first would hide the failure behind
-	stale content. -->
-{#if loadError}
+<!-- A load error replaces only the data pane: the tree, its role badge and menus, and the REPL
+	stay usable, so another data table or role can be picked and the connection tried by hand.
+	The tree then gets an empty schema: the cached one survives a failed refetch and would pass
+	stale content off as what this connection reaches. -->
+{#snippet errorPane()}
 	<div class="h-full w-full flex flex-col items-center justify-center gap-3 p-8">
 		<div class="max-w-2xl w-full flex flex-col gap-3">
-			<Alert type="error" title={loadError.title} size="xs">
-				{loadError.message}
+			<Alert type="error" title={loadError?.title ?? ''} size="xs">
+				{loadError?.message}
 			</Alert>
 			<div class="self-start">
-				<Button size="xs" color="light" startIcon={{ icon: RefreshCcw }} on:click={() => refresh()}>
+				<Button
+					unifiedSize="sm"
+					variant="default"
+					startIcon={{ icon: RefreshCcw }}
+					on:click={() => refresh()}
+				>
 					Retry
 				</Button>
 			</div>
@@ -247,9 +273,12 @@
 			/>
 		</div>
 	</div>
-{:else if dbSchema && ws && input}
+{/snippet}
+
+{#if (loadError || dbSchema) && ws && input}
 	{@const _input = input}
 	{@const dbType = getDbType(_input)}
+	{@const shownSchema = loadError || !dbSchema ? emptySchemaFor(_input) : dbSchema}
 	<Splitpanes horizontal>
 		<Pane class="relative">
 			<!-- svelte-ignore a11y_click_events_have_key_events -->
@@ -274,9 +303,11 @@
 			</div>
 			<DbManager
 				dbSupportsSchemas={dbSupportsSchemas(dbType)}
-				databaseIsEmpty={!Object.values(dbSchema.schema).flatMap((s) => Object.values(s)).length}
-				{dbSchema}
-				colDefs={colDefs.current}
+				databaseIsEmpty={!loadError &&
+					!Object.values(shownSchema.schema).flatMap((s) => Object.values(s)).length}
+				dbSchema={shownSchema}
+				mainPane={loadError ? errorPane : undefined}
+				colDefs={loadError ? undefined : colDefs.current}
 				dbTableOpsFactory={({ colDefs, tableKey, whereClause }) =>
 					dbTableOpsWithPreviewScripts({
 						colDefs,
@@ -306,7 +337,15 @@
 						: undefined}
 				{dbType}
 				refresh={() => refresh()}
-				{dbSelector}
+				{datatableTree}
+				{datatableTreeLoading}
+				{onSelectDatatable}
+				{onSelectRole}
+				workspace={ws}
+				currentRole={input.type === 'database' ? input.role : undefined}
+				bind:pendingAction
+				{onDatatableAction}
+				{canManageDatatable}
 				{onImport}
 				bind:selectedSchemaKey
 				bind:selectedTableKey
@@ -329,12 +368,12 @@
 					onSchemaChange={() => refresh()}
 					placeholderTableName={sortArray(
 						Object.keys(
-							dbSchema?.schema[
-								'public' in dbSchema?.schema
+							shownSchema.schema[
+								'public' in shownSchema.schema
 									? 'public'
-									: 'dbo' in dbSchema?.schema
+									: 'dbo' in shownSchema.schema
 										? 'dbo'
-										: Object.keys(dbSchema?.schema ?? {})?.[0]
+										: Object.keys(shownSchema.schema ?? {})?.[0]
 							] ?? {}
 						)
 					)?.[0]}

frontend/src/lib/components/DBManagerDrawer.svelte

@@ -1,25 +1,25 @@
 <script lang="ts">
-	import { superadmin, userStore, workspaceStore } from '$lib/stores'
-	import { WorkspaceService } from '$lib/gen'
+	import { enterpriseLicense, superadmin, userStore, workspaceStore } from '$lib/stores'
+	import { WorkspaceService, type DataTableTables } from '$lib/gen'
+	import { listUsableDatatableRoles } from './datatableUsableRoles'
 	import Button from './common/button/Button.svelte'
 	import Drawer from './common/drawer/Drawer.svelte'
 	import DrawerContent from './common/drawer/DrawerContent.svelte'
 	import Select from './select/Select.svelte'
-	import {
-		ArrowLeft,
-		Copy,
-		Download,
-		Expand,
-		LoaderCircle,
-		Minimize,
-		RefreshCcw,
-		Upload
-	} from 'lucide-svelte'
+	import { ArrowLeft, Copy, Download, Expand, Minimize, RefreshCcw, Upload } from 'lucide-svelte'
 	import DBManagerContent from './DBManagerContent.svelte'
+	import type { PendingRowAction } from './DBManager.svelte'
 	import DataTableMigrationsButton from './workspaceSettings/DataTableMigrationsButton.svelte'
+	import DataTablePermissionsButton from './workspaceSettings/DataTablePermissionsButton.svelte'
 	import { resource } from 'runed'
-	import { untrack } from 'svelte'
+	import { tick, untrack } from 'svelte'
 	import type { DbManagerUriState } from './dbManagerDrawerModel.svelte'
+	import {
+		ADMIN_DATATABLE_ROLE,
+		datatableNameTakesRole,
+		defaultMigrationRole,
+		type DatatableRowAction
+	} from './dbTypes'
 	import ResourcePicker from './ResourcePicker.svelte'
 	import Alert from './common/alert/Alert.svelte'
 	import { sendUserToast } from '$lib/toast'
@@ -41,31 +41,113 @@
 	// the editor that opened it (set via openDrawer), else the nav workspace.
 	let ws = $derived(uriState.workspace ?? $workspaceStore)
 
-	// Load available datatables when drawer opens with datatable input
-	const datatables = resource<string[]>([], async () => {
-		if (!ws) return []
-		try {
-			return (await WorkspaceService.listDataTables({ workspace: ws })).map((d) => d.name)
-		} catch (e) {
-			console.error('Failed to load datatables:', e)
-			return []
-		}
-	})
+	// A create started on a data table other than the current one: survives the
+	// re-mount the switch causes.
+	let pendingAction = $state<PendingRowAction | undefined>(undefined)
 
-	const datatableItems = $derived(
-		datatables.current.map((dt) => ({
-			value: dt,
-			label: dt
-		}))
+	// Read once through primitives: the getters return values of a freshly parsed URL, which
+	// changes on every table click, and the listings below must not refetch for that.
+	const selectedDatatable = $derived(uriState.selectedDatatable)
+	const selectedRole = $derived(uriState.selectedRole)
+
+	// Roles the caller may use, to settle the role before anything connects. Offering only
+	// these is a convenience: the server refuses any other.
+	const usableRoles = resource(
+		() => [ws, selectedDatatable] as const,
+		async ([workspace, datatable]) => {
+			if (!workspace || !datatable) return undefined
+			try {
+				return {
+					datatable,
+					...(await listUsableDatatableRoles(workspace, datatable))
+				}
+			} catch (e) {
+				// Never leave the drawer waiting on this: fall back to the
+				// unpermissioned shape so it opens and the server picks the role.
+				console.error('Failed to load datatable roles:', e)
+				return { datatable, permissioned: false, roles: [], default_role: ADMIN_DATATABLE_ROLE }
+			}
+		}
 	)
 
-	// Refetch datatables when switching to a datatable input
+	// A resource keeps its previous value while refetching, and roles are per data
+	// table: settling from the last one's answer would connect to the new data
+	// table as a role it may not even have.
+	const rolesOfCurrent = $derived(
+		usableRoles.current?.datatable === selectedDatatable ? usableRoles.current : undefined
+	)
+
+	// Nothing that connects runs until the role is settled: a first round sent without a role
+	// would run — and cache — as whatever the server defaults to.
+	const roleSettled = $derived(
+		!uriState.isDatatableInput ||
+			(rolesOfCurrent !== undefined &&
+				(!rolesOfCurrent.permissioned ||
+					rolesOfCurrent.roles.length === 0 ||
+					selectedRole !== undefined ||
+					// Its reference cannot name a role, so it connects as the default one.
+					(selectedDatatable !== undefined && !datatableNameTakesRole(selectedDatatable))))
+	)
+
+	// Make the role explicit before anything queries the data table, so the URL, the
+	// cache and every migration the manager writes name it. A role already in the URL
+	// is kept even when it is not usable: the server refuses it, visibly.
 	$effect(() => {
-		if (uriState.isDatatableInput) {
-			untrack(() => datatables.refetch())
-		}
+		const roles = rolesOfCurrent
+		if (
+			!roles?.permissioned ||
+			selectedRole !== undefined ||
+			(selectedDatatable !== undefined && !datatableNameTakesRole(selectedDatatable))
+		)
+			return
+		const effective = roles.roles.includes(roles.default_role) ? roles.default_role : roles.roles[0]
+		if (effective) untrack(() => (uriState.selectedRole = effective))
 	})
 
+	const contentInput = $derived.by(() => {
+		const input = uriState.effectiveInput
+		if (input?.type !== 'database' || selectedDatatable === undefined) return input
+		const migrationRole = defaultMigrationRole(
+			selectedDatatable,
+			rolesOfCurrent?.permissioned,
+			rolesOfCurrent?.default_role
+		)
+		return migrationRole === undefined ? input : { ...input, migrationRole }
+	})
+
+	// Every data table with its schemas and tables, in one call: this is what the
+	// left pane's tree navigates, so it has to cover the data tables the user is
+	// not currently on, not just the selected one. The privileges it reports are
+	// the connected role's, so the role picked on the open data table is part of
+	// what is being asked. Gated on the drawer being open on a data table: this
+	// reaches every data table's database in turn, and the component is mounted on
+	// every logged-in page.
+	let datatablesRun = 0
+	const datatables = resource(
+		() =>
+			[
+				open && uriState.isDatatableInput,
+				ws,
+				selectedDatatable,
+				selectedRole,
+				roleSettled
+			] as const,
+		async ([active, workspace, roleFor, role, settled]): Promise<DataTableTables[]> => {
+			if (!active || !workspace) return []
+			if (!settled) return untrack(() => datatables.current)
+			const run = ++datatablesRun
+			try {
+				const result = await WorkspaceService.listDataTableTables({ workspace, roleFor, role })
+				// An answer for a selection that has since changed describes another role.
+				return run === datatablesRun ? result : untrack(() => datatables.current)
+			} catch (e) {
+				console.error('Failed to load datatables:', e)
+				return run === datatablesRun ? [] : untrack(() => datatables.current)
+			}
+		},
+		{ initialValue: [] }
+	)
+
 	function handleClose() {
 		uriState.closeDrawer()
 		dbManagerContent?.clearReplResult()
@@ -78,6 +160,10 @@
 		if (!open) {
 			expand = false
 			uriState.closeDrawer()
+			// An action asked for on one data table must not be waiting when the
+			// drawer is next opened on another database — or on no data table at
+			// all, where nothing would recognise it as foreign.
+			pendingAction = undefined
 		}
 	})
 
@@ -97,6 +183,8 @@
 	let importDrawerOpen = $state(false)
 	let importLoading = $state(false)
 	let importSource = $state<string | undefined>(undefined)
+	/** Which database an import writes into; set when driven from a tree row. */
+	let importTarget = $state<string | undefined>(undefined)
 	let importBehavior = $state<'schema_only' | 'schema_and_data'>('schema_only')
 
 	let isPostgresqlInput = $derived(
@@ -116,13 +204,49 @@
 		return toSourceIdentifier(input.resourcePath)
 	}
 
+	// The tree's row menus act on the data table of the row that was clicked, which
+	// is not necessarily the one currently open — so the target is set first and the
+	// headless modals are keyed on it.
+	let actionDatatable = $state<string | undefined>(undefined)
+	let migrationsModal = $state<DataTableMigrationsButton | undefined>()
+	let permissionsDrawer = $state<DataTablePermissionsButton | undefined>()
+
+	async function runDatatableAction(datatable: string, action: DatatableRowAction) {
+		actionDatatable = datatable
+		// Let the keyed block above mount against the new target before driving it.
+		await tick()
+		switch (action) {
+			case 'migrations':
+				migrationsModal?.open()
+				break
+			case 'roles':
+				permissionsDrawer?.open()
+				break
+			case 'export':
+				await handleExportSchema(`datatable://${datatable}`)
+				break
+			case 'import':
+				importTarget = `datatable://${datatable}`
+				importDrawerOpen = true
+				break
+		}
+	}
+
 	function refreshManager() {
 		dbManagerContent?.refresh()
 		dbManagerContent?.dbManager()?.dbTable()?.refresh()
+		refreshRoles()
 	}
 
-	async function handleExportSchema() {
-		const source = currentSourceIdentifier()
+	/** Re-read what the tree and the role picker show: both are answers about the
+	 * data table's roles, which the permissions drawer can have just changed. */
+	function refreshRoles() {
+		datatables.refetch()
+		usableRoles.refetch()
+	}
+
+	async function handleExportSchema(explicitSource?: string) {
+		const source = explicitSource ?? currentSourceIdentifier()
 		if (!source || !ws) return
 		try {
 			exportResult = await WorkspaceService.exportPgSchema({
@@ -137,7 +261,7 @@
 
 	async function handleImportDatabase() {
 		if (!importSource || !ws) return
-		const target = currentSourceIdentifier()
+		const target = importTarget ?? currentSourceIdentifier()
 		if (!target) return
 		importLoading = true
 		try {
@@ -183,52 +307,48 @@
 		noPadding
 		id="db-manager-drawer"
 	>
-		{#if uriState.effectiveInput && ws}
-			{#key uriState.selectedDatatable}
+		{#if contentInput && ws && roleSettled}
+			{#key `${selectedDatatable}~${selectedRole ?? ''}`}
 				<DBManagerContent
 					bind:this={dbManagerContent}
-					input={uriState.effectiveInput}
+					input={contentInput}
 					workspace={uriState.workspace}
+					datatableTree={uriState.isDatatableInput ? datatables.current : undefined}
+					datatableTreeLoading={datatables.loading}
+					onSelectDatatable={(dt) => (uriState.selectedDatatable = dt)}
+					onSelectRole={(dt, role) => {
+						// Setting the data table clears the role, so the order matters.
+						uriState.selectedDatatable = dt
+						uriState.selectedRole = role
+					}}
+					bind:pendingAction
+					canManageDatatable={!!($superadmin || $userStore?.is_admin) &&
+						!!$enterpriseLicense &&
+						!isCloudHosted()}
+					onDatatableAction={runDatatableAction}
 					bind:workerTag={() => workerTag.tag, (v) => (workerTag.tag = v)}
 					bind:hasReplResult
 					bind:selectedSchemaKey={uriState.selectedSchema}
 					bind:selectedTableKey={uriState.selectedTable}
 					onImport={enableImportExport
-						? (mode) => ((importDrawerOpen = true), (importBehavior = mode))
+						? (mode) => (
+								(importTarget = undefined),
+								(importDrawerOpen = true),
+								(importBehavior = mode)
+							)
 						: undefined}
-				>
-					{#snippet dbSelector()}
-						{#if uriState.isDatatableInput}
-							{#if datatables.loading}
-								<div class="flex items-center gap-2 text-tertiary ml-2">
-									<LoaderCircle size={14} class="animate-spin" />
-									<span class="text-sm">Loading...</span>
-								</div>
-							{:else if datatables.current.length >= 1}
-								<Select
-									transformInputSelectedText={(s) => `Datatable: ${s}`}
-									items={datatableItems}
-									bind:value={uriState.selectedDatatable}
-									placeholder="Select data table"
-									size="md"
-								/>
-							{/if}
-						{/if}
-					{/snippet}
-				</DBManagerContent>
+				></DBManagerContent>
 			{/key}
 		{/if}
 		{#snippet actions()}
-			{#if uriState.isDatatableInput && uriState.selectedDatatable && ws}
-				<DataTableMigrationsButton
-					workspace={ws}
-					datatable={uriState.selectedDatatable}
-					onSchemaChanged={refreshManager}
-				/>
-			{/if}
-			{#if enableImportExport}
-				<Button startIcon={{ icon: Download }} onClick={handleExportSchema}>Export</Button>
-				<Button startIcon={{ icon: Upload }} onClick={() => (importDrawerOpen = true)}>
+			<!-- A data table exports and imports from its row menu in the tree; a plain
+				 database has no tree row to hold them. -->
+			{#if enableImportExport && !uriState.isDatatableInput}
+				<Button startIcon={{ icon: Download }} onClick={() => handleExportSchema()}>Export</Button>
+				<Button
+					startIcon={{ icon: Upload }}
+					onClick={() => ((importTarget = undefined), (importDrawerOpen = true))}
+				>
 					Import
 				</Button>
 			{/if}
@@ -260,6 +380,27 @@
 	</DrawerContent>
 </Drawer>
 
+{#if actionDatatable && ws}
+	{#key actionDatatable}
+		<DataTableMigrationsButton
+			bind:this={migrationsModal}
+			hideTrigger
+			workspace={ws}
+			datatable={actionDatatable}
+			onSchemaChanged={refreshManager}
+		/>
+		{#if $enterpriseLicense && !isCloudHosted()}
+			<DataTablePermissionsButton
+				bind:this={permissionsDrawer}
+				hideTrigger
+				workspace={ws}
+				datatable={actionDatatable}
+				onSaved={refreshRoles}
+			/>
+		{/if}
+	{/key}
+{/if}
+
 <Drawer bind:open={exportDrawerOpen} size="800px" offset={offset + 1}>
 	<DrawerContent title="Export Schemas" on:close={() => (exportDrawerOpen = false)}>
 		{#if exportResult}

frontend/src/lib/components/DBTableEditor.svelte

@@ -503,7 +503,7 @@
 		{/if}
 		{#if askingForConfirmation?.codeContent}
 			<div
-				class="bg-surface-secondary border border-surface-selected rounded-md p-2 relative group"
+				class="bg-surface-secondary border border-surface-selected rounded-md p-2 relative group min-w-0"
 			>
 				<button
 					class="absolute top-2 right-2 opacity-0 group-hover:opacity-100 transition-opacity p-1 rounded hover:bg-surface-hover"
@@ -512,9 +512,7 @@
 				>
 					<ClipboardCopy size={14} />
 				</button>
-				<pre class="whitespace-pre-wrap text-sm"
-					><code>{askingForConfirmation.codeContent}</code></pre
-				>
+				<pre class="overflow-x-auto text-sm"><code>{askingForConfirmation.codeContent}</code></pre>
 			</div>
 		{/if}
 	</ConfirmationModal>

frontend/src/lib/components/DatatableRoleBadge.svelte

@@ -0,0 +1,66 @@
+<script lang="ts">
+	import { ChevronDown } from 'lucide-svelte'
+	import SelectDropdown from './select/SelectDropdown.svelte'
+	import Badge from './common/badge/Badge.svelte'
+	import { clickOutside } from '$lib/utils'
+
+	let {
+		role,
+		roles,
+		onSelect
+	}: {
+		/** The role in effect, shown on the badge. */
+		role: string
+		/** The roles the caller may switch to. */
+		roles: string[]
+		onSelect: (role: string) => void
+	} = $props()
+
+	let open = $state(false)
+	let anchorEl: HTMLSpanElement | undefined = $state()
+	const items = $derived(roles.map((r) => ({ label: r, value: r })))
+
+	// The table picker's drawer opens at `disposables + 10000`, which the
+	// dropdown's own z-index would sit under.
+	const dropdownClass = 'z-[20000]'
+</script>
+
+<span
+	bind:this={anchorEl}
+	class="relative flex min-w-0"
+	use:clickOutside={{ onClickOutside: () => (open = false) }}
+>
+	<Badge
+		clickable
+		color="gray"
+		wrapperClass="min-w-0"
+		class="min-w-0 gap-0.5 pl-2 pr-1 bg-surface-sunken hover:bg-surface-sunken text-primary
+			transition-[filter,transform] hover:brightness-95 active:brightness-90 active:scale-[0.97]
+			{open ? 'brightness-95' : ''}"
+		onclick={(e) => {
+			// The row underneath folds on click, and picking a role is not that.
+			e.stopPropagation()
+			open = !open
+		}}
+	>
+		<!-- A long role name gives way rather than pushing the row's own actions
+		     past its right edge. -->
+		<span class="truncate">{role}</span>
+		<ChevronDown
+			size={11}
+			class="shrink-0 text-secondary transition-transform {open ? 'rotate-180' : ''}"
+		/>
+	</Badge>
+	<SelectDropdown
+		processedItems={items}
+		value={role}
+		{open}
+		listAutoWidth={false}
+		class={dropdownClass}
+		getInputRect={anchorEl && (() => anchorEl!.getBoundingClientRect())}
+		onSelectValue={(item) => {
+			open = false
+			if (item.value !== role) onSelect(item.value)
+		}}
+	/>
+</span>

frontend/src/lib/components/DdlMigrationGuard.svelte

@@ -6,8 +6,18 @@
 	import { joinSqlStatements, splitSqlRuns } from './sqlDdl'
 	import { logDdlGuardChoice } from './workspaceSettings/datatableTelemetry'
 	import { CornerDownLeft } from 'lucide-svelte'
+	import { withMigrationRole } from './datatableMigrationRole'
 
-	let { workspace, datatable }: { workspace: string; datatable: string } = $props()
+	let {
+		workspace,
+		datatable,
+		role
+	}: {
+		workspace: string
+		datatable: string
+		/** The role the editor runs as. The migration declares it, or it would run as admin. */
+		role?: string
+	} = $props()
 
 	type Choice = 'run' | 'migrate' | 'cancel'
 
@@ -73,7 +83,7 @@
 	function openMigrationModal(sql: string): Promise<boolean> {
 		return new Promise((resolve) => {
 			resolveMigrationClosed = (created: boolean) => resolve(created)
-			newMigrationModal?.open({ codeUp: sql })
+			newMigrationModal?.open({ codeUp: withMigrationRole(sql, role) })
 		})
 	}
 
@@ -145,6 +155,11 @@
 				migrations rather than run ad-hoc. Create a migration for it instead?
 			{/if}
 		</p>
+		{#if role}
+			<p class="text-sm text-secondary">
+				It will run as role <span class="font-mono">{role}</span>.
+			</p>
+		{/if}
 		<pre
 			class="text-xs whitespace-pre-wrap font-mono bg-surface-secondary rounded p-3 max-h-48 overflow-auto"
 			>{promptSql}</pre

frontend/src/lib/components/InstanceSettings.svelte

@@ -1093,7 +1093,10 @@
 							migrations are set up and used, how often an empty workspace home is seen, how often
 							the home page’s create menu and hub-project picker are opened and from which entry
 							point, the name of any public hub project imported from the home page and how far that
-							import got, and whether a pre-approved trial offer was opened, last 30 days)</li
+							import got, whether a pre-approved trial offer was opened, whether data tables are put
+							under roles and whether callers name a role or take the default, and which kinds of
+							access change (grant, revoke, ownership, default privileges) are applied to data
+							tables, last 30 days)</li
 						>
 						<li
 							>feature adoption (counts of which flow, script, trigger, worker and data table
@@ -1159,7 +1162,10 @@
 							migrations are set up and used, how often an empty workspace home is seen, how often
 							the home page’s create menu and hub-project picker are opened and from which entry
 							point, the name of any public hub project imported from the home page and how far that
-							import got, and whether a pre-approved trial offer was opened, last 30 days)</li
+							import got, whether a pre-approved trial offer was opened, whether data tables are put
+							under roles and whether callers name a role or take the default, and which kinds of
+							access change (grant, revoke, ownership, default privileges) are applied to data
+							tables, last 30 days)</li
 						>
 						<li
 							>feature adoption (counts of which flow, script, trigger, worker and data table

frontend/src/lib/components/SqlRepl.svelte

@@ -103,14 +103,21 @@
 			// We don't always put the fix by default for row ordering concerns
 			let transformedCode = code
 			if (doPostgresRowToJsonFix) {
-				transformedCode = statements
-					.map((statement) => {
-						if (READ_OPS.some((op) => statement.trim().toUpperCase().startsWith(op))) {
-							return `SELECT row_to_json(__t__) FROM (${statement}) __t__`
-						}
-						return statement
-					})
-					.join(';')
+				// Rebuilt from the pruned statements, which drops the leading comment block — and
+				// with it the `-- role <name>` annotation that decides which login the query runs
+				// as. Carry it over, or the retry connects as the data table's default role and a
+				// query the first attempt was denied succeeds on the second.
+				const leadingAnnotations = code.match(/^(?:[^\S\n]*\n|[^\S\n]*--[^\n]*\n)*/)?.[0] ?? ''
+				transformedCode =
+					leadingAnnotations +
+					statements
+						.map((statement) => {
+							if (READ_OPS.some((op) => statement.trim().toUpperCase().startsWith(op))) {
+								return `SELECT row_to_json(__t__) FROM (${statement}) __t__`
+							}
+							return statement
+						})
+						.join(';')
 			}
 			const dbArg = getDatabaseArg(input)
 
@@ -216,5 +223,10 @@
 </Splitpanes>
 
 {#if datatableName && ws}
-	<DdlMigrationGuard bind:this={ddlGuard} workspace={ws} datatable={datatableName} />
+	<DdlMigrationGuard
+		bind:this={ddlGuard}
+		workspace={ws}
+		datatable={datatableName}
+		role={input.type === 'database' ? (input.role ?? input.migrationRole) : undefined}
+	/>
 {/if}

frontend/src/lib/components/Star.svelte

@@ -9,9 +9,10 @@
 		kind: FavoriteKind
 		summary?: string
 		workspaceId?: string
+		size?: number
 	}
 
-	let { path, kind, workspaceId, summary }: Props = $props()
+	let { path, kind, workspaceId, summary, size = 16 }: Props = $props()
 
 	let buttonHover = $state(false)
 	let starred = $derived(favoriteManager.isStarred(path, kind))
@@ -31,14 +32,14 @@
 >
 	{#if starred}
 		{#if buttonHover}
-			<StarOff size={16} fill="currentcolor" />
+			<StarOff {size} fill="currentcolor" />
 		{:else}
-			<Star size={16} fill="currentcolor" />
+			<Star {size} fill="currentcolor" />
 		{/if}
 	{:else}
 		<Star
 			class={!buttonHover ? 'opacity-60' : ''}
-			size={16}
+			{size}
 			fill={buttonHover ? 'currentcolor' : 'none'}
 		/>
 	{/if}

frontend/src/lib/components/apps/components/display/dbtable/utils.ts

@@ -282,7 +282,8 @@ const scriptsV2: typeof legacyScripts = {
 		...legacyScripts.postgresql,
 		code: `
 SELECT table_name, column_name, udt_name, column_default, is_nullable, nsp.nspname AS table_schema FROM information_schema.columns
-RIGHT JOIN pg_namespace nsp ON table_schema = nsp.nspname WHERE nsp.nspname NOT IN ('information_schema', 'pg_toast', 'pg_catalog')`
+RIGHT JOIN pg_namespace nsp ON table_schema = nsp.nspname WHERE nsp.nspname NOT IN ('information_schema', 'pg_toast', 'pg_catalog')
+AND NOT starts_with(nsp.nspname, 'pg_') AND has_schema_privilege(nsp.oid, 'USAGE')`
 	}
 }
 

frontend/src/lib/components/common/confirmationModal/ConfirmationModal.svelte

@@ -186,7 +186,7 @@
 									<Icon class={theme[type].classes.icon} />
 								</div>
 							{/if}
-							<div class={twMerge('ml-0 text-left flex-1 ', showIcon ? 'ml-4' : '')}>
+							<div class={twMerge('ml-0 text-left flex-1 min-w-0', showIcon ? 'ml-4' : '')}>
 								<h3 class="text-lg font-medium text-primary">
 									{title}
 								</h3>

frontend/src/lib/components/copilot/chat/AIChatManager.svelte.ts

@@ -732,12 +732,14 @@ export class AIChatManager implements ChatViewHost {
 	/** Every mounted flow editor. */
 	#flowEditors = new Set<FlowAIChatHelpers>()
 	appAiChatHelpers = $state<AppAIChatHelpers | undefined>(undefined)
-	/** Datatable creation policy: enabled flag, datatable name, and optional schema */
+	/** Datatable creation policy: enabled flag, datatable name, optional schema, and the role the
+	 * app uses each data table through */
 	datatableCreationPolicy = $state<{
 		enabled: boolean
 		datatable: string | undefined
 		schema: string | undefined
-	}>({ enabled: false, datatable: undefined, schema: undefined })
+		roles?: Record<string, string>
+	}>({ enabled: false, datatable: undefined, schema: undefined, roles: undefined })
 	pendingNewCode = $state<string | undefined>(undefined)
 	apiTools = $state<Tool<any>[]>([])
 	aiChatInput = $state<AIChatInput | null>(null)

frontend/src/lib/components/copilot/chat/DatatableCreationPolicy.svelte

@@ -67,6 +67,7 @@
 		<DefaultDatabaseSelector
 			datatable={aiChatManager.datatableCreationPolicy.datatable}
 			schema={aiChatManager.datatableCreationPolicy.schema}
+			roles={aiChatManager.datatableCreationPolicy.roles}
 			onChange={handleDefaultChange}
 			description="Set the default datatable and schema for new tables. When table creation is enabled, AI can create tables here if needed."
 		/>

frontend/src/lib/components/copilot/chat/app/core.ts

@@ -18,6 +18,7 @@ import {
 	type AppCodeSelectionElement,
 	type AppDatatableElement
 } from '../context'
+import { appDatatableRole, sdkDatatableCall } from '$lib/components/raw_apps/dataTableRefUtils'
 
 // Backend runnable types
 export type BackendRunnableType = 'script' | 'flow' | 'hubscript' | 'inline'
@@ -921,9 +922,20 @@ export function prepareAppSystemMessage(customPrompt?: string): ChatCompletionSy
 	const policy = aiChatManager.datatableCreationPolicy
 	const datatableName = policy.datatable ?? 'main'
 	const schemaPrefix = policy.schema ? `${policy.schema}.` : ''
-	// Use wmill.datatable() for 'main' (default), otherwise wmill.datatable('name')
-	const datatableCall =
-		datatableName === 'main' ? 'wmill.datatable()' : `wmill.datatable('${datatableName}')`
+	// A role names the privileges the app's queries run with, so it has to be in the code the
+	// model writes.
+	const datatableRole = appDatatableRole(policy.roles, datatableName)
+	const tsDatatableCall = sdkDatatableCall(datatableName, datatableRole, 'typescript')
+	const pyDatatableCall = sdkDatatableCall(datatableName, datatableRole, 'python')
+	const roleEntries = Object.entries(policy.roles ?? {})
+	const rolesNote =
+		roleEntries.length > 0
+			? `\n\nThis app uses these data tables through a role: ${roleEntries
+					.map(([dt, role]) => `\`${dt}\` as \`${role}\``)
+					.join(
+						', '
+					)}. Always pass that role when calling \`wmill.datatable\` on them, as in the examples. The role only reaches what it was granted, so a query on a table it lacks privileges on fails with \`permission denied\`.`
+			: ''
 
 	let content = `You are a helpful assistant that creates and edits apps on the Windmill platform. Apps are defined as a collection of files that contains both the frontend and the backend.
 
@@ -1024,7 +1036,7 @@ Backend runnables should only perform **data operations** (SELECT, INSERT, UPDAT
 import * as wmill from 'windmill-client';
 
 export async function main(user_id: string) {
-  const sql = ${datatableCall};
+  const sql = ${tsDatatableCall};
   const user = await sql\`SELECT * FROM ${schemaPrefix}users WHERE id = \${user_id}\`.fetchOne();
   return user;
 }
@@ -1035,12 +1047,12 @@ export async function main(user_id: string) {
 import wmill
 
 def main(user_id: str):
-    db = ${datatableCall}
+    db = ${pyDatatableCall}
     user = db.query('SELECT * FROM ${schemaPrefix}users WHERE id = $1', user_id).fetch_one()
     return user
 \`\`\`
 
-Use these examples for normal datatable access.
+Use these examples for normal datatable access.${rolesNote}
 
 ### Schema Modifications (DDL) - Use exec_datatable_sql tool ONLY
 

frontend/src/lib/components/copilot/chat/datatableTools.ts

@@ -2,6 +2,7 @@ import { z } from 'zod'
 import { WorkspaceService, type CompletedJob } from '$lib/gen'
 import type { DataTableTables } from '$lib/gen/types.gen'
 import { runScript } from '$lib/components/jobs/utils'
+import { datatableReference } from '$lib/components/dbTypes'
 import {
 	createToolDef,
 	executeTestRun,
@@ -15,9 +16,9 @@ import {
  *
  * Datatables are workspace-level managed PostgreSQL databases. The backend
  * endpoints used here (`list_datatable_tables`, `get_datatable_table_schema`)
- * and SQL execution (`datatable://<name>`) are gated only by workspace
- * membership, so these tools need no app context and operate directly on the
- * workspace. This is the unrestricted counterpart to the app-mode datatable
+ * and SQL execution (`datatable://<name>`) need no app context: the server
+ * decides what the caller reaches, as the datatable role they name or its
+ * default. This is the unrestricted counterpart to the app-mode datatable
  * tools in `app/core.ts`, which additionally filter by the app's whitelist.
  */
 
@@ -31,9 +32,19 @@ const memo = <T>(factory: () => T): (() => T) => {
 
 // ============= Pure workspace-scoped operations =============
 
-/** List all datatables configured in the workspace, with their schema/table names. */
-export async function listDatatables(workspace: string): Promise<DataTableTables[]> {
-	return await WorkspaceService.listDataTableTables({ workspace })
+/** List the datatables configured in the workspace, with their schema/table names: all of them as
+ * their default role, or only `datatableName`, as `role` when one is given. */
+export async function listDatatables(
+	workspace: string,
+	datatableName?: string,
+	role?: string
+): Promise<DataTableTables[]> {
+	if (datatableName === undefined) return await WorkspaceService.listDataTableTables({ workspace })
+	return await WorkspaceService.listDataTableTables({
+		workspace,
+		datatableName,
+		...(role !== undefined && { roleFor: datatableName, role })
+	})
 }
 
 /** Get the columns (column_name -> compact_type) of one datatable table. */
@@ -41,13 +52,15 @@ export async function getDatatableColumns(
 	workspace: string,
 	datatableName: string,
 	schemaName: string,
-	tableName: string
+	tableName: string,
+	role?: string
 ): Promise<Record<string, string>> {
 	const schema = await WorkspaceService.getDataTableTableSchema({
 		workspace,
 		datatableName,
 		schemaName,
-		tableName
+		tableName,
+		role
 	})
 	return schema.columns
 }
@@ -81,7 +94,26 @@ const NO_DATATABLES_CONFIGURED_MESSAGE =
 
 // ============= Tool definitions =============
 
-const getListDatatablesSchema = memo(() => z.object({}))
+// The same rule the server applies to `-- role <name>`; a name it would refuse fails here instead.
+const getRoleSchema = memo(() =>
+	z
+		.string()
+		.regex(/^[A-Za-z0-9_-]{1,63}$/)
+		.optional()
+		.describe(
+			"The datatable role to connect as, when the code you are working on uses one (an app's `data.roles` entry, or the `role` it passes to wmill.datatable). Omit for the datatable's default role."
+		)
+)
+
+const getListDatatablesSchema = memo(() =>
+	z.object({
+		datatable_name: z
+			.string()
+			.optional()
+			.describe('List only this datatable. Required with `role`.'),
+		role: getRoleSchema()
+	})
+)
 const getListDatatablesToolDef = memo(() =>
 	createToolDef(
 		getListDatatablesSchema(),
@@ -94,7 +126,8 @@ const getGetDatatableTableSchemaSchema = memo(() =>
 	z.object({
 		datatable_name: z.string().describe('The datatable name to inspect, e.g. "main".'),
 		schema_name: z.string().describe('The schema name, e.g. "public".'),
-		table_name: z.string().describe('The table name to inspect.')
+		table_name: z.string().describe('The table name to inspect.'),
+		role: getRoleSchema()
 	})
 )
 const getGetDatatableTableSchemaToolDef = memo(() =>
@@ -117,6 +150,7 @@ const getExecDatatableSqlSchema = memo(() =>
 			.describe(
 				'The SQL query to execute. Supports SELECT, INSERT, UPDATE, DELETE, CREATE TABLE, ALTER TABLE, DROP TABLE, etc. For SELECT queries, results are returned as an array of objects. A newly created table will appear in list_datatables automatically.'
 			),
+		role: getRoleSchema(),
 		background: z
 			.boolean()
 			.optional()
@@ -217,10 +251,18 @@ export function getDatatableTools(): Tool<{}>[] {
 		{
 			def: getListDatatablesToolDef(),
 			planModeSafe: true,
-			fn: async ({ workspace, toolId, toolCallbacks }) => {
+			fn: async ({ args, workspace, toolId, toolCallbacks }) => {
 				toolCallbacks.setToolStatus(toolId, { content: 'Listing datatables...' })
 				try {
-					const metadata = await listDatatables(workspace)
+					const parsedArgs = getListDatatablesSchema().parse(args ?? {})
+					if (parsedArgs.role !== undefined && parsedArgs.datatable_name === undefined) {
+						throw new Error('`role` needs `datatable_name`, the datatable it is a role of')
+					}
+					const metadata = await listDatatables(
+						workspace,
+						parsedArgs.datatable_name,
+						parsedArgs.role
+					)
 					if (metadata.length === 0) {
 						toolCallbacks.setToolStatus(toolId, {
 							content: 'No datatables configured — set one up in workspace settings'
@@ -236,7 +278,18 @@ export function getDatatableTools(): Tool<{}>[] {
 					toolCallbacks.setToolStatus(toolId, {
 						content: `Listed ${metadata.length} datatable(s) with ${totalTables} table(s)`
 					})
-					return JSON.stringify(metadata, null, 2)
+					// Only what the model acts on: the roles it may pass, not the creation privileges
+					// the manager's UI gates on.
+					return JSON.stringify(
+						metadata.map((d) => ({
+							datatable_name: d.datatable_name,
+							schemas: d.schemas,
+							...(d.error && { error: d.error }),
+							...(d.permissioned && { usable_roles: d.usable_roles, default_role: d.default_role })
+						})),
+						null,
+						2
+					)
 				} catch (e) {
 					const errorMsg = `Error listing datatables: ${e instanceof Error ? e.message : String(e)}`
 					toolCallbacks.setToolStatus(toolId, { content: errorMsg, error: errorMsg })
@@ -257,7 +310,8 @@ export function getDatatableTools(): Tool<{}>[] {
 						workspace,
 						parsedArgs.datatable_name,
 						parsedArgs.schema_name,
-						parsedArgs.table_name
+						parsedArgs.table_name,
+						parsedArgs.role
 					)
 					toolCallbacks.setToolStatus(toolId, {
 						content: `Retrieved schema for ${parsedArgs.schema_name}.${parsedArgs.table_name}`
@@ -300,7 +354,7 @@ export function getDatatableTools(): Tool<{}>[] {
 							requestBody: {
 								language: 'postgresql',
 								content: parsedArgs.sql,
-								args: { database: `datatable://${name}` }
+								args: { database: datatableReference(name, parsedArgs.role) }
 							}
 						}),
 					workspace,

frontend/src/lib/components/copilot/chat/global/core.ts

@@ -1406,7 +1406,12 @@ Data Tables:
 - Datatables are workspace-scoped managed PostgreSQL databases, shared across the workspace (not owned by any single app). They must be configured by the user in their workspace settings (Workspace settings → Data Tables); they cannot be created via SQL.
 - Use list_datatables to discover the available datatables and their tables. Reuse an existing table rather than creating a duplicate. If list_datatables reports none, this is a blocking prerequisite — tell the user to set up a datatable in their workspace settings and stop; do not assume a "main" datatable exists or call exec_datatable_sql.
 - Use get_datatable_table_schema only when you need a table's column names/types; list_datatables is enough for table-list or availability summaries.
-- Use exec_datatable_sql to explore data, run queries, mutate rows, or change schema (CREATE/ALTER/DROP). Creating a table is a normal CREATE TABLE statement — it appears in list_datatables afterward, with no registration step.
+- Use exec_datatable_sql to explore data, run queries, mutate rows, or change schema (CREATE/ALTER/DROP). Creating a table is a normal CREATE TABLE statement — it appears in list_datatables afterward, with no registration step.${
+		isCloudHosted()
+			? ''
+			: `
+- A raw app may use a datatable through a role (\`data.roles\` in its raw_app.yaml). When working on such an app, pass that role to the datatable tools, and to wmill.datatable in its runnables, so you see and change only what the app itself can.`
+	}
 - When writing runnable code (inline app runnables, scripts, flow modules) that reads or writes datatable data at runtime, it accesses a datatable via wmill.datatable(). Default to TypeScript (bun) unless the user asked for another language. Call get_instructions with subject "datatable" and language "bun" for the TypeScript SQL SDK reference (or language "python3" for Python) — it returns only that language so you get just what you need.${
 		skills.length > 0
 			? `

frontend/src/lib/components/datatableAcl/PgAclEditor.svelte

@@ -0,0 +1,283 @@
+<script lang="ts">
+	import { WorkspaceService, type AclChange, type AclTarget, type DatatableAclInfo } from '$lib/gen'
+	import { resource } from 'runed'
+	import { Trash2 } from 'lucide-svelte'
+	import { sendUserToast } from '$lib/toast'
+	import { Alert, Button } from '../common'
+	import ConfirmationModal from '../common/confirmationModal/ConfirmationModal.svelte'
+	import Select from '../select/Select.svelte'
+	import DataTable from '../table/DataTable.svelte'
+	import Head from '../table/Head.svelte'
+	import Row from '../table/Row.svelte'
+	import Cell from '../table/Cell.svelte'
+	import PgGrantBuilder from './PgGrantBuilder.svelte'
+	import {
+		ADMIN_ROLE,
+		blockingSources,
+		grantKey,
+		grantScopeLabel,
+		groupGrants,
+		revocablePrivileges,
+		revokeScopeOf,
+		uncoveredCreators
+	} from './aclScopes'
+
+	let {
+		workspace,
+		datatable,
+		target
+	}: {
+		workspace: string
+		datatable: string
+		/** What owner and grants are read and written for. */
+		target: AclTarget
+	} = $props()
+
+	const acl = resource(
+		() => [workspace, datatable, target] as const,
+		async ([ws, dt, t]) =>
+			await WorkspaceService.getDatatableAcl({
+				workspace: ws,
+				datatableName: dt,
+				kind: t.kind,
+				schema: t.kind === 'database' ? undefined : t.schema,
+				table: t.kind === 'table' ? t.table : undefined
+			})
+	)
+
+	// Nothing is written before its SQL has been shown, and the apply runs exactly that SQL: the
+	// server plans again and refuses if the result differs.
+	let pending = $state<
+		{ change: AclChange; statements: string[]; warnings: string[]; title: string } | undefined
+	>(undefined)
+	let planning = $state(false)
+	let applying = $state(false)
+
+	const info: DatatableAclInfo | undefined = $derived(acl.current)
+	const grantRows = $derived(groupGrants(info?.grants ?? []))
+	const ownerItems = $derived(
+		info
+			? (info.roles.includes(info.owner) ? info.roles : [info.owner, ...info.roles]).map((r) => ({
+					value: r,
+					label: r
+				}))
+			: []
+	)
+	/** A revoke listed per object takes them all: say that it does. */
+	const pendingCoversObjects = $derived(
+		pending?.change.type === 'revoke' && (pending.change.objects?.length ?? 0) > 1
+	)
+
+	function errorText(e: any): string {
+		return e?.body ?? e?.message ?? String(e)
+	}
+
+	async function confirm(change: AclChange, title: string) {
+		planning = true
+		try {
+			const plan = await WorkspaceService.planDatatableAcl({
+				workspace,
+				datatableName: datatable,
+				requestBody: { target, change }
+			})
+			pending = { change, statements: plan.statements, warnings: plan.warnings, title }
+		} catch (e) {
+			sendUserToast(errorText(e), true)
+		} finally {
+			planning = false
+		}
+	}
+
+	async function apply() {
+		if (!pending) return
+		applying = true
+		try {
+			await WorkspaceService.applyDatatableAcl({
+				workspace,
+				datatableName: datatable,
+				requestBody: { target, change: pending.change, statements: pending.statements }
+			})
+			sendUserToast(pending.title)
+			pending = undefined
+			await acl.refetch()
+		} catch (e) {
+			sendUserToast(errorText(e), true)
+		} finally {
+			applying = false
+		}
+	}
+</script>
+
+{#if acl.error}
+	<Alert type="error" title="Could not read access" size="xs">{errorText(acl.error)}</Alert>
+{:else if !info}
+	<span class="text-xs text-secondary">Loading…</span>
+{:else}
+	<div class="flex flex-col gap-4">
+		{#if !info.editable}
+			<span class="text-xs text-secondary">
+				Read only: access is changed by the admins of the workspace that governs this data table, on
+				Windmill Enterprise Edition.
+			</span>
+		{/if}
+
+		{#if target.kind !== 'database'}
+			<section class="flex flex-col gap-2">
+				<div class="flex flex-col gap-0.5">
+					<span class="text-xs font-semibold text-emphasis">Owner</span>
+					<span class="text-xs text-secondary">
+						{target.kind === 'schema'
+							? 'The role that owns the schema and everything already in it, except what belongs to an extension, which stays with the extension. Changing it also keeps the new owner in reach of what the current roles create here from then on; a role added afterwards is not covered.'
+							: 'The role that owns the table. Its owner may always read and write it, and is who ALTER and DROP answer to.'}
+					</span>
+				</div>
+				{#if info.editable}
+					<Select
+						items={ownerItems}
+						disabled={planning || applying}
+						size="sm"
+						class="w-64"
+						bind:value={
+							() => info.owner,
+							(role) => {
+								// The select shows what the database says; a pick is a request, and only the
+								// applied change moves it.
+								if (role && role !== info.owner) {
+									confirm({ type: 'set_owner', role }, `Ownership transferred to ${role}`)
+								}
+							}
+						}
+					/>
+				{:else}
+					<span class="font-mono text-xs">{info.owner}</span>
+				{/if}
+			</section>
+		{/if}
+
+		<section class="flex flex-col gap-2">
+			<div class="flex flex-col gap-0.5">
+				<span class="text-xs font-semibold text-emphasis">Grants</span>
+				<span class="text-xs text-secondary">
+					{target.kind === 'database'
+						? 'What each role may do on the database itself — CREATE is the right to create schemas in it — and what default privileges set database-wide give it on what is created later, in every schema. No schema can take those back.'
+						: 'What each role may do here, beyond what it owns.'}
+				</span>
+			</div>
+			{#if info.editable}
+				<PgGrantBuilder
+					{target}
+					roles={info.roles}
+					disabled={planning || applying}
+					supportsMaintain={info.supports_maintain}
+					dbname={info.dbname}
+					onAdd={({ role, privileges, scope }) =>
+						confirm(
+							{ type: 'grant', role, privileges, scope },
+							`Granted ${privileges.join(', ')} to ${role}`
+						)}
+				/>
+			{/if}
+			{#if grantRows.length === 0}
+				<span class="text-xs text-secondary">No grants yet.</span>
+			{:else}
+				<DataTable size="xs">
+					<Head>
+						<tr>
+							<Cell head first>Role</Cell>
+							<Cell head>Privileges</Cell>
+							<Cell head>On</Cell>
+							<Cell head last></Cell>
+						</tr>
+					</Head>
+					<tbody class="divide-y">
+						{#each grantRows as grant (grantKey(grant))}
+							{@const revokeScope = revokeScopeOf(grant)}
+							{@const revocable = revocablePrivileges(grant, target)}
+							{@const blocked = blockingSources(grant, revocable)}
+							{@const uncovered = uncoveredCreators(grant, info.roles)}
+							<Row>
+								<Cell first>{grant.grantee}</Cell>
+								<Cell wrap
+									><span class="font-mono text-2xs">{grant.privileges.join(', ')}</span></Cell
+								>
+								<Cell wrap>
+									{grantScopeLabel(grant)}
+									{#if blocked.length > 0}
+										<span
+											class="text-2xs text-secondary"
+											title="Only this role can take the grant back: Postgres revokes a grant through the role that made it"
+										>
+											from {blocked.join(', ')}
+										</span>
+									{/if}
+									{#if uncovered.length > 0}
+										<span
+											class="text-2xs text-secondary"
+											title="A default privilege covers only the roles it was granted for: grant it again to cover these"
+										>
+											· not for what {uncovered.join(', ')}
+											{uncovered.length === 1 ? 'creates' : 'create'}
+										</span>
+									{/if}
+								</Cell>
+								<Cell last>
+									<!-- What `admin` holds is what every role here connects through, so it is not
+									this editor's to take away. -->
+									{#if info.editable && revokeScope && revocable.length > 0 && blocked.length === 0 && info.roles.includes(grant.grantee) && grant.grantee !== ADMIN_ROLE}
+										<Button
+											unifiedSize="xs"
+											variant="subtle"
+											iconOnly
+											startIcon={{ icon: Trash2 }}
+											title="Revoke {revocable.join(', ')}"
+											disabled={planning || applying}
+											onClick={() =>
+												confirm(
+													{
+														type: 'revoke',
+														role: grant.grantee,
+														privileges: revocable,
+														scope: revokeScope,
+														objects: grant.objects
+													},
+													`Revoked ${revocable.join(', ')} from ${grant.grantee}`
+												)}
+										/>
+									{/if}
+								</Cell>
+							</Row>
+						{/each}
+					</tbody>
+				</DataTable>
+			{/if}
+		</section>
+	</div>
+{/if}
+
+<ConfirmationModal
+	open={!!pending}
+	title="Run the following?"
+	confirmationText="Run"
+	type="info"
+	alwaysPortal
+	loading={applying}
+	onConfirmed={apply}
+	onCanceled={() => (pending = undefined)}
+>
+	<div class="flex flex-col gap-3 min-w-0">
+		{#if pendingCoversObjects}
+			<Alert type="info" title="This covers every listed object" size="xs">
+				The same privileges on several objects read as one row, and are revoked together.
+			</Alert>
+		{/if}
+		{#each pending?.warnings ?? [] as warning (warning)}
+			<Alert type="warning" title="Warning" size="xs">{warning}</Alert>
+		{/each}
+		<span class="text-sm text-secondary">
+			Runs against <span class="font-mono">{datatable}</span> in a single transaction:
+		</span>
+		<pre class="overflow-auto text-xs bg-surface-secondary p-3 rounded select-all max-h-80"
+			>{(pending?.statements ?? []).join(';\n')};</pre
+		>
+	</div>
+</ConfirmationModal>

frontend/src/lib/components/datatableAcl/PgGrantBuilder.svelte

@@ -0,0 +1,95 @@
+<script lang="ts">
+	import type { AclTarget } from '$lib/gen'
+	import { Plus } from 'lucide-svelte'
+	import { Button } from '../common'
+	import Select from '../select/Select.svelte'
+	import MultiSelect from '../select/MultiSelect.svelte'
+	import { privilegesOf, scopeSql, scopesOf, type AclScope } from './aclScopes'
+
+	let {
+		target,
+		roles,
+		supportsMaintain = false,
+		dbname,
+		disabled = false,
+		onAdd
+	}: {
+		target: AclTarget
+		/** Roles the grant can be handed to. */
+		roles: string[]
+		/** Postgres 17+, which has one more table privilege to offer. */
+		supportsMaintain?: boolean
+		/** Names the database in the statement a database target builds. */
+		dbname?: string
+		disabled?: boolean
+		onAdd: (grant: { role: string; privileges: string[]; scope: AclScope }) => void
+	} = $props()
+
+	let role = $state<string | undefined>(undefined)
+	let scope = $state<AclScope>('target')
+	let privileges = $state<string[]>([])
+
+	const available = $derived(privilegesOf(scope, target.kind, supportsMaintain))
+	const statement = $derived(
+		privileges.length && role
+			? `GRANT ${privileges.join(', ')} ON ${scopeSql(scope, target, dbname)} TO ${role}`
+			: undefined
+	)
+</script>
+
+<div class="flex flex-col gap-2 border rounded-md p-3">
+	<div class="flex flex-wrap items-center gap-2 text-xs text-secondary">
+		<span class="font-mono text-primary">GRANT</span>
+		<MultiSelect
+			bind:value={privileges}
+			items={available.map((p) => ({ value: p, label: p }))}
+			placeholder="privileges"
+			{disabled}
+			size="sm"
+			class="min-w-48"
+		/>
+		<span class="font-mono text-primary">ON</span>
+		<Select
+			bind:value={
+				() => scope,
+				(s) => {
+					if (!s) return
+					scope = s
+					// A privilege only exists for some objects — SELECT means nothing on a function —
+					// so drop what the new scope cannot carry rather than send it.
+					const allowed = privilegesOf(s, target.kind, supportsMaintain)
+					privileges = privileges.filter((p) => allowed.includes(p))
+				}
+			}
+			items={scopesOf(target.kind)}
+			{disabled}
+			size="sm"
+			class="w-52"
+		/>
+		<span class="font-mono text-primary">TO</span>
+		<Select
+			bind:value={role}
+			items={roles.map((r) => ({ value: r, label: r }))}
+			placeholder="role"
+			{disabled}
+			size="sm"
+			class="w-40"
+		/>
+		<Button
+			unifiedSize="sm"
+			variant="default"
+			startIcon={{ icon: Plus }}
+			disabled={disabled || !role || privileges.length === 0}
+			onClick={() => {
+				if (!role) return
+				onAdd({ role, privileges: [...privileges], scope })
+				privileges = []
+			}}
+		>
+			Add
+		</Button>
+	</div>
+	{#if statement}
+		<pre class="text-2xs text-tertiary overflow-x-auto">{statement}</pre>
+	{/if}
+</div>

frontend/src/lib/components/datatableAcl/aclScopes.test.ts

@@ -0,0 +1,178 @@
+import { describe, expect, it } from 'vitest'
+import type { AclGrant } from '$lib/gen'
+import {
+	blockingSources,
+	grantKey,
+	groupGrants,
+	revocablePrivileges,
+	revokeScopeOf,
+	uncoveredCreators
+} from './aclScopes'
+
+const table = (name: string) => ({ name, kind: 'TABLE' })
+const by = (role: string, privileges: string[], reachable = true) => ({
+	role,
+	privileges,
+	reachable
+})
+const byAdmin = (grant: Omit<AclGrant, 'sources'>): AclGrant => ({
+	...grant,
+	sources: [by('admin', grant.privileges)]
+})
+
+describe('grantKey', () => {
+	it('tells apart a table and a function of the same name', () => {
+		const row = (object: { name: string; kind: string; args?: string }) => ({
+			grantee: 'analytics',
+			privileges: ['SELECT'],
+			objects: [object],
+			sources: [by('admin', ['SELECT'])]
+		})
+		expect(grantKey(row(table('orders')))).not.toBe(
+			grantKey(row({ name: 'orders', kind: 'FUNCTION', args: '' }))
+		)
+	})
+})
+
+describe('groupGrants', () => {
+	// A row's revoke names every object in it, so a row must only hold what one revoke may take.
+	it('folds the same privileges on objects of one kind, and nothing else', () => {
+		const grants: AclGrant[] = [
+			{ grantee: 'analytics', privileges: ['SELECT'], object: table('orders') },
+			{ grantee: 'analytics', privileges: ['SELECT'], object: table('salaries') },
+			{ grantee: 'operator', privileges: ['SELECT'], object: table('orders') },
+			{ grantee: 'analytics', privileges: ['INSERT', 'SELECT'], object: table('events') },
+			{ grantee: 'analytics', privileges: ['SELECT'], object: { name: 's', kind: 'SEQUENCE' } },
+			{ grantee: 'analytics', privileges: ['SELECT'], future: 'TABLES' },
+			{ grantee: 'analytics', privileges: ['USAGE'] }
+		].map(byAdmin)
+		const rows = groupGrants(grants)
+		expect(rows.map((r) => [r.grantee, r.privileges, r.objects, r.future])).toEqual([
+			['analytics', ['SELECT'], [table('orders'), table('salaries')], undefined],
+			['operator', ['SELECT'], [table('orders')], undefined],
+			['analytics', ['INSERT', 'SELECT'], [table('events')], undefined],
+			['analytics', ['SELECT'], [{ name: 's', kind: 'SEQUENCE' }], undefined],
+			['analytics', ['SELECT'], [], 'TABLES'],
+			['analytics', ['USAGE'], [], undefined]
+		])
+	})
+
+	// A revoke takes the row back from every source, so the row must name them all, with what each
+	// gave.
+	it('keeps every source of the grants it folds', () => {
+		const grants: AclGrant[] = [
+			{
+				grantee: 'analytics',
+				privileges: ['SELECT'],
+				object: table('orders'),
+				sources: [by('admin', ['SELECT'])]
+			},
+			{
+				grantee: 'analytics',
+				privileges: ['SELECT'],
+				object: table('salaries'),
+				sources: [by('admin', ['SELECT']), by('operator', ['SELECT'])]
+			}
+		]
+		expect(groupGrants(grants)[0].sources).toEqual([
+			by('admin', ['SELECT']),
+			by('operator', ['SELECT'])
+		])
+	})
+})
+
+describe('revoke of a row', () => {
+	const row = (future?: string) => ({
+		grantee: 'analytics',
+		privileges: ['SELECT'],
+		objects: [],
+		future,
+		sources: [by('admin', ['SELECT'])]
+	})
+
+	it('takes back only what the editor may revoke on the database', () => {
+		const database = { ...row(), privileges: ['CONNECT', 'CREATE'] }
+		expect(revocablePrivileges(database, { kind: 'database' })).toEqual(['CREATE'])
+		expect(revocablePrivileges(database, { kind: 'schema', schema: 'public' })).toEqual([
+			'CONNECT',
+			'CREATE'
+		])
+		// Set database-wide, so not one a schema's revoke could take back either.
+		const schemasLater = { ...row('SCHEMAS'), privileges: ['CREATE'] }
+		expect(revocablePrivileges(schemasLater, { kind: 'database' })).toEqual([])
+	})
+
+	it('maps default privileges to their scope, and refuses the ones it has none for', () => {
+		expect(revokeScopeOf(row())).toBe('target')
+		expect(revokeScopeOf(row('TABLES'))).toBe('future_tables')
+		expect(revokeScopeOf(row('TYPES'))).toBeUndefined()
+		expect(revokeScopeOf({ ...row(), objects: [{ name: 'mood', kind: 'TYPE' }] })).toBeUndefined()
+	})
+
+	// Postgres takes a grant back only through its source: offering the revoke would promise what
+	// the plan then refuses. But only the sources of what is revoked count: the catalog's CONNECT
+	// on the database comes from its owner, out of reach, and must not hold back a CREATE the
+	// editor granted.
+	it('is held back only by a source out of reach for what it takes', () => {
+		const database = {
+			...row(),
+			privileges: ['CONNECT', 'CREATE'],
+			sources: [by('postgres', ['CONNECT'], false), by('admin', ['CREATE'])]
+		}
+		const revocable = revocablePrivileges(database, { kind: 'database' })
+		expect(blockingSources(database, revocable)).toEqual([])
+		expect(blockingSources(database, ['CONNECT'])).toEqual(['postgres'])
+		const partly = {
+			...row('TABLES'),
+			sources: [by('admin', ['SELECT']), by('postgres', ['SELECT'], false)]
+		}
+		expect(blockingSources(partly, ['SELECT'])).toEqual(['postgres'])
+	})
+
+	// Whether a grant can be taken back depends on its object, so a row folding several objects is
+	// only revocable if each of its grants is.
+	it('is held back by a source out of reach on any of the objects it folds', () => {
+		const grants: AclGrant[] = [
+			{
+				grantee: 'analytics',
+				privileges: ['SELECT'],
+				object: table('orders'),
+				sources: [by('admin', ['SELECT'])]
+			},
+			{
+				grantee: 'analytics',
+				privileges: ['SELECT'],
+				object: table('salaries'),
+				sources: [by('admin', ['SELECT'], false)]
+			}
+		]
+		const [folded] = groupGrants(grants)
+		expect(folded.objects).toHaveLength(2)
+		expect(blockingSources(folded, ['SELECT'])).toEqual(['admin'])
+		// Folding reads the grants, never rewrites them.
+		expect(grants[0].sources[0].reachable).toBe(true)
+	})
+})
+
+describe('uncoveredCreators', () => {
+	// A default privilege binds only the creating roles it was granted for: a role added since is
+	// left out until the grant is made again.
+	it('names the roles a created-later row leaves out', () => {
+		const future = {
+			grantee: 'analytics',
+			privileges: ['SELECT'],
+			objects: [],
+			future: 'TABLES',
+			sources: [by('admin', ['SELECT']), by('analytics', ['SELECT'])]
+		}
+		expect(uncoveredCreators(future, ['admin', 'analytics', 'late'])).toEqual(['late'])
+		expect(uncoveredCreators({ ...future, future: undefined }, ['late'])).toEqual([])
+		// Set by a role outside the catalog, it was never meant to cover the catalog's roles.
+		expect(
+			uncoveredCreators({ ...future, sources: [by('postgres', ['SELECT'], false)] }, [
+				'admin',
+				'late'
+			])
+		).toEqual([])
+	})
+})