Let AI read PostgreSQL. Review changes before they run.

1. Start a local PostgreSQL server

Start Docker Desktop and keep GateRook running. The example assumes that a development endpoint named showcase already exists and that your AI app is connected to it. In the screenshots, that app is Codex.

Run the following in a terminal. The container publishes PostgreSQL only on the computer's loopback interface, at 127.0.0.1:15432; it does not publish a database port on your LAN. Use a different container name or port if either is already occupied.

export POSTGRES_PASSWORD="$(openssl rand -hex 24)"

docker run -d \
  --name gaterook-postgres-showcase \
  -p 127.0.0.1:15432:5432 \
  -e POSTGRES_PASSWORD \
  -e POSTGRES_DB=gaterook_demo \
  --health-cmd 'pg_isready -U postgres -d gaterook_demo' \
  --health-interval 2s \
  --health-timeout 3s \
  --health-retries 30 \
  postgres:16.13

unset POSTGRES_PASSWORD

docker inspect --format '{{.State.Health.Status}}' \
  gaterook-postgres-showcase

Wait until the health check says healthy. Then create the sample table and a separate database login:

docker exec -i gaterook-postgres-showcase \
  psql -U postgres -d gaterook_demo -v ON_ERROR_STOP=1 <<'SQL'
CREATE ROLE demo_agent LOGIN PASSWORD 'local-demo-only';

CREATE TABLE public.orders (
    id integer PRIMARY KEY,
    customer_name text NOT NULL,
    status text NOT NULL
        CHECK (status IN ('pending', 'paid', 'shipped')),
    total numeric(10,2) NOT NULL
);

INSERT INTO public.orders VALUES
    (1001, 'Avery Stone', 'pending', 129.90),
    (1002, 'Morgan Reed', 'paid', 89.00),
    (1003, 'Riley Chen', 'pending', 249.00),
    (1004, 'Jordan Lee', 'shipped', 49.50);

GRANT CONNECT ON DATABASE gaterook_demo TO demo_agent;
GRANT USAGE ON SCHEMA public TO demo_agent;
GRANT SELECT, UPDATE ON public.orders TO demo_agent;
SQL

local-demo-only is a public, disposable tutorial password. Use it only for this local fixture. GateRook will connect as demo_agent, not as the PostgreSQL administrator. The explicit table grants allow SELECT and UPDATE on public.orders; they do not grant INSERT, DELETE, or ownership. UPDATE is included so that the approval flow can be demonstrated.

2. Choose the PostgreSQL connector

In GateRook, open Connections and select Add connection. The list below is filtered to keep unrelated connections out of view; filtering is not required to add a connection.

Select PostgreSQL, then Continue. Its four built-in tools cover schema discovery, table descriptions, read queries, and changes that require approval.

3. Enter the server and credentials

Fill in the connection fields:

The name is a slug used in tool calls and Activity filters. Choose it before saving: existing calls and policies refer to it, so the saved connection cannot simply be renamed.

GateRook connects from the computer running its core. Here, the host and port point to the container's published port. Encrypted here stores the credential encrypted with GateRook's master key. The database password is not part of the SQL tool arguments sent by the AI app.

4. Configure transport and schema access

Expand Advanced and set:

Leave the other advanced fields at their defaults. For a remote database, use the default Verify the CA and host name (verify-full) with a correctly configured TLS server; provide its CA certificate when it uses a private CA. The local tutorial's SSL setting is specific to this container.

5. Select the database

Select Load databases and tick only gaterook_demo. Leave postgres unchecked. A database appearing in the discovery list does not automatically make it available through the saved connection.

Keep DEV Development selected. Its description is explicit: mutations still wait for approval. If you change the server, credentials, or transport, reload the database list before continuing.

6. Test the connection

Select Continue to open the test step. GateRook connects with the values you entered and displays the server version, connection time, and a permissions summary.

The example reports Connected · PostgreSQL 16.13 and detects that the user can read and write. The write summary is broad: the database grants created above remain the authority for which operations the role can actually perform. In this fixture, the role has only SELECT and UPDATE on the orders table.

For an analytical connection that never needs writes, use a database role with only the necessary read privileges. Here, continue with the tutorial role so that you can review an update later.

7. Add the connection to showcase

Continue to Add to endpoint. Untick default if the wizard selected it, and tick only showcase. This controls which AI apps can use the new connection: apps connected to other endpoints do not gain its tools from this selection.

Review the proposed modes, then select Save connection:

After saving, the connection page shows Healthy, 1 endpoint, and 4 tools on showcase. The saved password is represented by an encrypted version, rather than a readable value.

8. Understand the request path

Open Endpoints → showcase. The connection diagram shows the path from Codex through the endpoint to postgres-demo.

The AI app sends a tool name and arguments, such as a connection name and SQL. GateRook checks the endpoint's tool mode and applicable policy, supplies the database credential inside the connector, executes the permitted operation, and records the outcome in Activity.

In Tools & policies, confirm that the three read tools use Read only and sql_execute uses Approval. Keep Bypass unselected for this walkthrough. The endpoint can also display gateway tools in Off mode; those are separate from the four PostgreSQL tools.

If an already running AI session still has the old tool list, refresh its MCP tools or reconnect the client before asking it to use the new connection. No database password needs to be copied into the chat.

9. Discover the table and run read queries

Ask your connected AI app:

Use the showcase endpoint and the postgres-demo connection. List the tables in gaterook_demo, describe public.orders, and show the orders sorted by id. Then summarize the order count and total by status.

The schema tools return one table, public.orders, with four columns and an id primary key. A read call uses arguments such as:

{
  "connection": "postgres-demo",
  "database": "gaterook_demo",
  "sql": "SELECT id, customer_name, status, total FROM public.orders ORDER BY id",
  "limit": 10
}

Before the update, the result is:

sql_query runs a validated read in a read-only PostgreSQL transaction and rolls that transaction back when finished. Row, response-size, and timeout limits still apply. In the tested configuration, the tool advertises a maximum of 1,000 rows and a five-second timeout; these calls request only ten rows.

Open Activity, filter by the connection or endpoint, and select the corresponding sql_query row. Its details show the client, endpoint, SQL arguments, and decision.

The policy decision says Allowed: this read ran immediately. The result section shows its execution summary, size, hash, masking count, and timing.

The second query groups the same data:

SELECT status, COUNT(*) AS order_count, SUM(total) AS total_amount
FROM public.orders
GROUP BY status
ORDER BY status;

10. Review and approve one change

Ask the AI app to mark only order 1001 as shipped, provided it is still pending. It should use sql_execute with this exact statement:

UPDATE public.orders
SET status = 'shipped'
WHERE id = 1001 AND status = 'pending';

The WHERE clause narrows the target to one known order and checks its starting state. GateRook pauses the operation and returns an approval handle. At this point, the change has not executed.

The chat's approval card shows Waiting for approval and links to GateRook. The following two screenshots show the client-side card before and after the person's decision in the application.

In GateRook's Approvals screen, review:

• The connection postgres-demo, the DEV marker, and endpoint showcase.
• The exact SQL, especially its table, SET value, and WHERE clause.
• The rule dev.sql.write-approval, which requires a person to approve the change.
• The impact preview: the target public.orders, an estimate of 1 row from EXPLAIN, a transaction that rolls back on error, and a five-second statement timeout.

The row estimate is a planning estimate; the execution result tells you how many rows were actually changed. Add a comment if useful, then select Approve and run. To refuse the request, select Deny. The request also expires if nobody decides before its timer runs out; the example has a five-minute deadline.

The approval applies to this exact action. The AI should poll its existing approval handle for the outcome, rather than submit the update again. Approval happens in GateRook; opening the chat card alone does not approve it.

After approval, the card changes to Completed. The actual result was a committed transaction with 1 row updated.

11. Verify the database change

Ask the AI app to read order 1001 again using sql_query:

SELECT id, customer_name, status, total
FROM public.orders
WHERE id = 1001;

The result is now:

This verifies the saved database state independently of the approval card. The follow-up read is also recorded in Activity.

12. Follow the full audit trail in Activity

Open Activity → Agent calls. Enter this filter and press Enter:

endpoint:showcase connection:postgres-demo

Select the time range that covers your test. In this walkthrough, the filtered list contains six calls: schema discovery, table description, the initial SELECT, the grouped SELECT, the approved UPDATE, and the verification SELECT. Read calls show Allowed; the update shows Approved. Each row identifies the tool, connection, client, endpoint, and execution duration.

Open the sql_execute event to inspect its exact arguments and the policy that required approval.

Scroll to Approval and Result. The event connects the whole sequence: requested by Codex, desktop notification, approved by the person, and executed with one affected row. It also shows an approved-action hash and confirms that the executed action matches the approved action byte for byte.

Use this detail view to answer practical questions: Which AI app requested the change? Which endpoint and connection did it use? Why did it need approval? When was it approved? How many rows changed? How long did execution take?

Arguments and Policy decision explain the request and its authorization. Approval records the person's decision. Result and Timing show the outcome and duration. Result detail varies by tool: the read events here show a summary, size, and hash, while the approved write also exposes its structured execution result. Do not treat the audit log as a full database-result archive.

Masking follows the configured policies. These fictional records have no masked fields. Unrelated connection details have been excluded from the screenshots, and the unrelated endpoint name visible during selection has been redacted.

Keep or stop the demo

The tutorial leaves postgres-demo attached to showcase, with reads enabled and writes still requiring approval. The Docker container remains running so you can continue exploring.

To pause access without deleting the configuration, turn the connection's On switch off. That affects this connection across endpoints. Turning an endpoint off instead pauses access through that endpoint. Activity remains available for inspecting previous calls.

To stop the tutorial database while retaining its data:

docker stop gaterook-postgres-showcase

To resume it later:

docker start gaterook-postgres-showcase

Once it is healthy again, use Test connection in GateRook to check connectivity. A stopped container will make the connection unavailable until it is restarted.