Skip to content
bucker

Connecting a Postgres database

Bucker reads a managed Postgres without an agent on your side: you run one reviewed SQL script, paste the connection string of the role it creates, and Bucker's workers read statement statistics over verified TLS. This page is the whole contract: what the script grants, what Bucker will and will not send to your database, and how it fails.

What you do

  1. Read the script below. It is the same text db_connections_list returns with include: ["setup_script"], and its digest is recorded when you connect.
  2. Replace REPLACE_WITH_A_LONG_RANDOM_PASSWORD with a long random password. The script stops with an error while the placeholder is still there.
  3. Run it once, as an administrative role, connected to the database to monitor. Bucker never runs it and never creates the role.
  4. In Bucker, start a connection for a project (Settings, Connections), then paste postgres://bucker_monitor:<password>@host:port/database into the single-use connect link. If your host signs with a private certificate authority (DigitalOcean, Supabase, RDS and others do), paste its CA certificate as PEM text in the CA field. Remove ?sslmode=require and every other query parameter: Bucker refuses a URL that carries one.
  5. Bucker connects, checks the role and the server, and refuses with the missing privilege named if something is not as the script left it.

Only a person with egress:admin (an owner or admin) can enter the connection string. It is a human-only act: no agent, token or integration can do it, and it is audited.

The script, version 1

SHA-256 of the exact text: dbf124b7bb8dcde63b2ff324c30743b3132c4b64641b9210c78d2320e39e57f5

-- Bucker database monitoring setup, version 1.
--
-- Read this before you run it. Run it ONCE, as an administrative role, connected to the
-- database Bucker will monitor. Bucker never runs it and never creates this role: afterwards
-- you paste the connection string of bucker_monitor into Bucker and nothing else.
--
-- What it creates: a login role with no superuser, create, replication or row-security bypass
-- rights, at most two connections, read-only by default; membership in pg_read_all_stats;
-- SELECT on pg_stat_statements; and a "bucker" schema for Bucker's optional functions. It
-- reads no table's rows.
--
-- Before running: replace REPLACE_WITH_A_LONG_RANDOM_PASSWORD with a long random password. The script
-- stops with an error while the placeholder is still there.

BEGIN;

CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

DO $bucker$
DECLARE
  monitor_password text := 'REPLACE_WITH_A_LONG_RANDOM_PASSWORD';
BEGIN
  -- The comparison is spelled in two pieces so that replacing the placeholder everywhere cannot disarm it.
  IF monitor_password = ('REPLACE_WITH_' || 'A_LONG_RANDOM_PASSWORD') OR length(monitor_password) < 16 THEN
    RAISE EXCEPTION 'Edit the script first: set monitor_password to a long random password';
  END IF;
  IF NOT EXISTS (SELECT 1 FROM pg_catalog.pg_roles WHERE rolname = 'bucker_monitor') THEN
    EXECUTE format(
      'CREATE ROLE bucker_monitor WITH LOGIN PASSWORD %L NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS CONNECTION LIMIT 2',
      monitor_password
    );
  ELSE
    EXECUTE format('ALTER ROLE bucker_monitor WITH LOGIN PASSWORD %L', monitor_password);
  END IF;
END
$bucker$;

ALTER ROLE bucker_monitor SET statement_timeout = '2s';
ALTER ROLE bucker_monitor SET lock_timeout = '100ms';
ALTER ROLE bucker_monitor SET default_transaction_read_only = on;

GRANT pg_read_all_stats TO bucker_monitor;
GRANT SELECT ON pg_stat_statements TO bucker_monitor;

CREATE SCHEMA IF NOT EXISTS bucker;
GRANT USAGE ON SCHEMA bucker TO bucker_monitor;

-- An earlier draft of this script defined bucker.explain, a SECURITY DEFINER planner: planning
-- caller-supplied text with your administrative role's privileges reads any table that role can
-- read. It is removed wherever it exists, and this script creates nothing like it.
DROP FUNCTION IF EXISTS bucker.explain(text, text);

COMMIT;

With the optional cancel function

Allow Bucker to cancel one runaway statement (and nothing else) by running this variant instead. SHA-256: 5ebad74458e7c55ba6b91d07dcab9db7c6e3815355d52222cd3e9fbd4206f95c

-- Bucker database monitoring setup, version 1.
--
-- Read this before you run it. Run it ONCE, as an administrative role, connected to the
-- database Bucker will monitor. Bucker never runs it and never creates this role: afterwards
-- you paste the connection string of bucker_monitor into Bucker and nothing else.
--
-- What it creates: a login role with no superuser, create, replication or row-security bypass
-- rights, at most two connections, read-only by default; membership in pg_read_all_stats;
-- SELECT on pg_stat_statements; and a "bucker" schema for Bucker's optional functions. It
-- reads no table's rows.
--
-- Before running: replace REPLACE_WITH_A_LONG_RANDOM_PASSWORD with a long random password. The script
-- stops with an error while the placeholder is still there.

BEGIN;

CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

DO $bucker$
DECLARE
  monitor_password text := 'REPLACE_WITH_A_LONG_RANDOM_PASSWORD';
BEGIN
  -- The comparison is spelled in two pieces so that replacing the placeholder everywhere cannot disarm it.
  IF monitor_password = ('REPLACE_WITH_' || 'A_LONG_RANDOM_PASSWORD') OR length(monitor_password) < 16 THEN
    RAISE EXCEPTION 'Edit the script first: set monitor_password to a long random password';
  END IF;
  IF NOT EXISTS (SELECT 1 FROM pg_catalog.pg_roles WHERE rolname = 'bucker_monitor') THEN
    EXECUTE format(
      'CREATE ROLE bucker_monitor WITH LOGIN PASSWORD %L NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS CONNECTION LIMIT 2',
      monitor_password
    );
  ELSE
    EXECUTE format('ALTER ROLE bucker_monitor WITH LOGIN PASSWORD %L', monitor_password);
  END IF;
END
$bucker$;

ALTER ROLE bucker_monitor SET statement_timeout = '2s';
ALTER ROLE bucker_monitor SET lock_timeout = '100ms';
ALTER ROLE bucker_monitor SET default_transaction_read_only = on;

GRANT pg_read_all_stats TO bucker_monitor;
GRANT SELECT ON pg_stat_statements TO bucker_monitor;

CREATE SCHEMA IF NOT EXISTS bucker;
GRANT USAGE ON SCHEMA bucker TO bucker_monitor;

-- An earlier draft of this script defined bucker.explain, a SECURITY DEFINER planner: planning
-- caller-supplied text with your administrative role's privileges reads any table that role can
-- read. It is removed wherever it exists, and this script creates nothing like it.
DROP FUNCTION IF EXISTS bucker.explain(text, text);

-- OPTIONAL (you chose to allow cancelling a runaway statement): cancels ONE running statement,
-- identified by its process id AND the time its backend started, so a recycled process id can
-- never be cancelled by mistake. It never terminates a session, and it refuses a superuser's
-- backend, this role's own backend and its own.
CREATE OR REPLACE FUNCTION bucker.cancel_backend(target_pid integer, target_backend_start timestamptz)
RETURNS boolean
LANGUAGE plpgsql
SECURITY DEFINER
SET search_path = pg_catalog, pg_temp
AS $fn$
BEGIN
  IF target_pid = pg_backend_pid() THEN
    RETURN false;
  END IF;
  PERFORM 1
    FROM pg_stat_activity a
   WHERE a.pid = target_pid
     AND a.backend_start = target_backend_start
     AND a.datname = current_database()
     AND a.backend_type = 'client backend'
     AND a.state = 'active'
     AND a.usename IS DISTINCT FROM 'bucker_monitor'
     AND NOT EXISTS (SELECT 1 FROM pg_roles r WHERE r.rolname = a.usename AND r.rolsuper);
  IF NOT FOUND THEN
    RETURN false;
  END IF;
  RETURN pg_cancel_backend(target_pid);
END
$fn$;
REVOKE ALL ON FUNCTION bucker.cancel_backend(integer, timestamptz) FROM PUBLIC;
GRANT EXECUTE ON FUNCTION bucker.cancel_backend(integer, timestamptz) TO bucker_monitor;

COMMIT;

The cancel function takes a process id AND the time that backend started, so a recycled process id is never cancelled by mistake. It cancels a statement; it never terminates a session, and it refuses a superuser's backend and Bucker's own.

What the role can and cannot do

  • It is a login with no superuser, create-database, create-role, replication or row-security-bypass right, at most two connections, and read-only by default.
  • It is a member of pg_read_all_stats (statistics and the text of the statements the server has run; connecting stores none of it) and can SELECT from pg_stat_statements.
  • It reads no table's rows.
  • There is no plan function. An earlier draft of this script created bucker.explain, a SECURITY DEFINER function that planned a statement with the privileges of the role that ran the script; because the planner evaluates some function calls while it estimates, that let the monitoring role read any table the administrative role could. The script drops it if it exists, and verification refuses a role that can still execute one (explain_function_present).
  • Bucker never asks for, and the script never grants, pg_terminate_backend, ALTER SYSTEM, parameter changes, failover or resizing.
  • Verification refuses a role that holds any administrative power, so a connection string for your owner or admin role is rejected rather than trusted to be careful. Never give Bucker a Neon API key or a Supabase service_role key.

How Bucker connects

  • Verified TLS only. Bucker dials the address it resolved and checked, with your host name as the certificate name, against your CA (or the public roots). A server without TLS, or a certificate that does not verify, is a named error and nothing is sent. There is no unverified mode and no plaintext fallback.
  • Public addresses only. A host that resolves to a private, loopback, link-local or metadata address, or an internal name (*.internal, *.flycast), is refused before any connection. If your organization enforces an egress allow-list, the host must be on it; connecting adds it.
  • The collector is built not to be your outage. One session per database at a time, statement_timeout 2 s, lock_timeout 100 ms, application_name bucker-collector, read-only. Only pinned statements are ever sent (the list is in the code and pinned by a test). A breaker pauses collection after three consecutive timeouts or when fewer than three connection slots are free, and a rejected password or failed certificate pauses it until you verify again.
  • Allow Bucker's addresses. Allow the egress addresses shown in Bucker at your provider (trusted sources, security group, authorized networks).
  • Statistics from a database hosted in the EU are processed in the US region until an EU region exists.

When it fails

You see Meaning Fix
database_privileges_missing The message names each missing privilege Run the script again
role_too_powerful The role is a superuser or holds another administrative power Connect as bucker_monitor
explain_function_present The role can execute a bucker.explain left by an earlier draft of the script Run the current script, which drops it
database_tls_verification_failed The certificate is not signed by the CA Bucker holds, has expired or does not name the host Paste your provider's CA certificate
database_tls_unsupported The server does not speak TLS Enable TLS on the server
database_egress_refused The host is private, loopback, link-local or metadata Use the database's public address
database_auth_failed The role or password was rejected Check the password in the connection string

Server error text is untrusted: Bucker scrubs it, caps it at 500 characters and shows it as data, never as an instruction.

Agents

db_connections_list lists the databases of a project with platform, mode, server version, granted privileges, breaker state and the last error. With include: ["setup_script"] and a platform it returns the reviewed script and that platform's steps, before any database is connected. A person runs the script. There is no write tool: entering a credential is human-only.