docs: keep deployment integrations private

Author: sabino

CHANGELOG.md

@@ -19,7 +19,7 @@
   integration coverage.
 - Default release containers to Alpine, add a stripped scratch control-plane
   image, add checksummed native packages for PostgreSQL 14 through 18, and add
-  a CapRover one-click definition.
+  an optional one-click deployment definition.
 
 ## 0.2.0 - 2026-08-12
 

README.md

@@ -60,34 +60,14 @@ HTTPS requests to BrasilAPI and turn the JSON response into PostgreSQL rows.
 ```text
 browser ──> control plane ──SQL──> PostgreSQL + openapi_fdw
                                       │
-Metabase ─────────PostgreSQL──────────┤
+SQL clients ──────PostgreSQL──────────┤
                                       └──HTTPS──> external JSON APIs
 ```
 
 The control plane can be stopped after configuration. PostgreSQL keeps serving
 the foreign tables because the data plane has no dependency on the web app.
-Likewise, Metabase talks normal PostgreSQL; it does not need an OpenAPI plugin.
-
-## Connect Metabase
-
-Add the OpenAPI FDW PostgreSQL instance as a normal PostgreSQL database in
-Metabase. In Docker Compose, use `postgres:5432` from a container on the same
-network. In CapRover, use:
-
-```text
-Host:     srv-captain--openapi-fdw-db
-Port:     5432
-Database: openapi_fdw
-User:     openapi_fdw
-Password: <the PostgreSQL password configured at deployment>
-```
-
-The exact hostname changes if the CapRover app is given another name. No public
-database port is required when Metabase is in the same CapRover cluster.
-
-Metabase schema synchronization sees the imported foreign tables and their
-typed columns. Native SQL questions work immediately. Path-based endpoints
-need an equality predicate for every placeholder, as in the CEP example above.
+Any PostgreSQL-compatible client can query the tables without an OpenAPI-aware
+driver or plugin.
 
 ## Use any compatible OpenAPI document
 
@@ -291,7 +271,7 @@ reached 1,940 scans/s. Public network latency normally dominates; see
 ## Documentation
 
 - [Control plane and bundle format](docs/CONTROL_PLANE.md)
-- [Installation, containers, CapRover, and Metabase](docs/DEPLOYMENT.md)
+- [Installation and containers](docs/DEPLOYMENT.md)
 - [Architecture and trade-offs](docs/ARCHITECTURE.md)
 - [Original prototype audit](docs/AUDIT.md)
 - [Public API research](docs/API_RESEARCH.md)

control-plane/assets/app.js

@@ -248,9 +248,9 @@ async function copyConnectionSql(source) {
   const searchPath = schemas.length ? schemas.map(quoteIdentifier).join(", ") : "public";
   const firstSchema = schemas.length ? quoteIdentifier(schemas[0]) : "public";
   const firstTable = quoteIdentifier(source.tables[0]?.name || "table_name");
-  const sql = `-- Run in Metabase after connecting this PostgreSQL database\nSET search_path TO ${searchPath}, public;\n\n-- Every SELECT below performs a live HTTP request\nSELECT * FROM ${firstSchema}.${firstTable} LIMIT 20;`;
+  const sql = `-- Run in any PostgreSQL client\nSET search_path TO ${searchPath}, public;\n\n-- Every SELECT below performs a live HTTP request\nSELECT * FROM ${firstSchema}.${firstTable} LIMIT 20;`;
   await navigator.clipboard.writeText(sql);
-  toast("Metabase starter SQL copied.");
+  toast("Connection SQL copied.");
 }
 
 async function removeSource(source) {

control-plane/src/ui.rs

@@ -61,7 +61,7 @@ pub fn dashboard() -> String {
                         p class="eyebrow" { "LIVE DATA PLANE" }
                         h1 id="page-title" { "Turn an OpenAPI service into tables." }
                         p class="lede" {
-                            "Discover operations, review the SQL, import a schema, then query the remote API from PostgreSQL or Metabase."
+                            "Discover operations, review the SQL, import a schema, then query the remote API from PostgreSQL."
                         }
                     }
                     div class="metrics" aria-label="Control-plane summary" {

deploy/caprover/openapi-fdw.yml

@@ -47,13 +47,6 @@ caproverOneClickApp:
       CapRover overlay network by default.
     end: |-
       Open https://$$cap_appname.$$cap_root_domain and sign in with the control-plane token.
-
-      Metabase running on this CapRover cluster can connect with:
-      host: srv-captain--$$cap_appname-db
-      port: 5432
-      database: $$cap_pg_db
-      username: $$cap_pg_user
-      password: the PostgreSQL password entered above
   displayName: OpenAPI FDW
   isOfficial: false
   description: Query OpenAPI-described HTTP APIs as live PostgreSQL foreign tables.

docs/ARCHITECTURE.md

@@ -65,7 +65,7 @@ matters for local and low-latency services.
 browser --> stateless Rust control plane -- reviewed SQL --> PostgreSQL catalogs
                                                         |
                                                         v
-PostgreSQL planner/executor <---------------------- Metabase / SQL clients
+PostgreSQL planner/executor <---------------------- SQL clients
         |
         v
 supabase-wrappers native FDW callbacks

docs/CONTROL_PLANE.md

@@ -7,7 +7,7 @@ JavaScript. It does not proxy query traffic and it does not copy API data.
 ```text
 administrator browser --> control plane --> PostgreSQL DDL/catalogs
                                               |
-SQL clients and Metabase ---------------------+
+SQL clients ----------------------------------+
                                               |
                                               +--> external API on every scan
 ```
@@ -26,10 +26,9 @@ its foreign tables.
 | `OPENAPI_FDW_POOL_SIZE` | no | `8` | PostgreSQL connection-pool size, 1 through 64 |
 | `RUST_LOG` | no | `openapi_fdw_control=info` | Rust tracing filter |
 
-The current control-plane PostgreSQL connection uses `NoTls`. In Docker Compose
-or CapRover it should use a private container/overlay network and
-`sslmode=disable`. Do not expose that unencrypted connection across an
-untrusted network.
+The current control-plane PostgreSQL connection uses `NoTls`. In containers or
+an orchestrator it should use a private network and `sslmode=disable`. Do not
+expose that unencrypted connection across an untrusted network.
 
 The login token is held in process memory. A successful login receives a
 derived, HTTP-only, same-site session cookie; the administrator token itself is

docs/DEPLOYMENT.md

@@ -78,68 +78,24 @@ Then connect and run `CREATE EXTENSION openapi_fdw;`. If an FDW option names a
 secret environment variable, pass that variable to this PostgreSQL container,
 not to the control-plane container.
 
-## CapRover
+## Production operation
 
-[`deploy/caprover/openapi-fdw.yml`](../deploy/caprover/openapi-fdw.yml) is a
-CapRover v4 one-click definition. It creates:
-
-- `<app>`: the HTTPS control plane; and
-- `<app>-db`: private PostgreSQL 18 with a persistent volume mounted at
-  `/var/lib/postgresql`.
-
-In CapRover, choose **One-Click Apps/Databases**, use the template, provide an
-app name, keep separate long random PostgreSQL and administrator secrets, and
-deploy. Enable HTTPS and force HTTPS on the web app. PostgreSQL is deliberately
-not exposed as a web app and needs no public TCP mapping when its consumers are
-inside the same Swarm.
-
-For an app named `openapi-fdw`, another CapRover app reaches PostgreSQL at:
-
-```text
-srv-captain--openapi-fdw-db:5432
-```
-
-Back up the persistent PostgreSQL volume using the same process used for other
-CapRover databases. The control plane is stateless; its only required state is
-its environment configuration and the metadata stored in PostgreSQL.
+Keep PostgreSQL on a private network unless direct client access is required,
+persist `/var/lib/postgresql`, and use independent random values for the
+database password and control-plane administrator token. Terminate HTTPS in
+front of the control plane and retain its secure-cookie default.
 
 Upgrades should keep PostgreSQL on the same major unless a normal PostgreSQL
 major-version upgrade is performed. Updating a same-major image restarts the
 service with the existing volume and updated extension files. Run
 `ALTER EXTENSION openapi_fdw UPDATE;` when a future release introduces an
 extension upgrade script.
 
-## Metabase
-
-Add the deployment as a normal PostgreSQL database. For the CapRover example:
-
-```text
-Display name: OpenAPI FDW / BrasilAPI
-Host:         srv-captain--openapi-fdw-db
-Port:         5432
-Database:     openapi_fdw
-Username:     openapi_fdw
-Password:     <deployment PostgreSQL password>
-SSL:          off for the private CapRover overlay connection
-```
-
-Grant Metabase a read-only role instead of reusing the owner in a multi-user
-installation:
-
-```sql
-CREATE ROLE metabase_openapi LOGIN PASSWORD '<different random password>';
-GRANT CONNECT ON DATABASE openapi_fdw TO metabase_openapi;
-GRANT USAGE ON SCHEMA brasil TO metabase_openapi;
-GRANT SELECT ON ALL TABLES IN SCHEMA brasil TO metabase_openapi;
-ALTER DEFAULT PRIVILEGES IN SCHEMA brasil
-  GRANT SELECT ON TABLES TO metabase_openapi;
-```
-
-Metabase schema sync sees foreign tables and typed columns. Each question or
-native query that scans one performs live outbound API work, so dashboard
-refresh frequency and upstream rate limits still matter. For expensive or
-rate-limited datasets, explicitly materialize selected results in local tables
-on a schedule instead of treating the FDW as a cache.
+Any PostgreSQL-compatible client can connect with the standard host, port,
+database, user, and password fields. Prefer a dedicated read-only login and
+grant it only `CONNECT`, schema `USAGE`, foreign-server `USAGE`, and `SELECT`
+on the intended foreign tables. Each scan performs live outbound API work, so
+client refresh frequency and upstream rate limits still matter.
 
 ## Checksummed native installation