connectors

Set up the PostgreSQL connector

The PostgreSQL connector runs as part of the Ploy Connector, a single self-contained binary that initiates outbound HTTPS to Ploy and scans your Postgres instance from inside your network. It maps login roles to identities, NOLOGIN roles to groups, and role memberships to access edges. Optional role_management lets Ploy write membership changes via GRANT and REVOKE.

What you need before you start

  • The Ploy Connector binary for your platform (Linux amd64/arm64 or Windows amd64), downloaded from the Ploy console.

  • A PostgreSQL instance reachable from the connector host.

  • A connector bearer key from the Ploy admin UI. It must start with ploy_ct_.

  • Outbound HTTPS (port 443) from the connector host to api.joinploy.com.

Postgres permissions

The connector role needs different privileges depending on which features you enable.

For scan only (read-only):

  • Catalogue access to read pg_roles and pg_auth_members.

For role_management (write membership changes):

  • The connector role must have ADMIN OPTION on every role it manages, or be a PostgreSQL superuser.

Configure the connector

Create or edit the connector's config.yaml. On Linux the default path is /etc/ploy-connector/config.yaml; on Windows it is %ProgramData%\Ploy\Connector\config.yaml.

Add a PostgreSQL integration block. The slug (for example local-pg) must be unique within this connector:

backend:
  key: env://PLOY_CONNECTOR_KEY

integrations:
  local-pg:
    type: postgres
    enabled_features: [scan, role_management]
    credentials:
      url: postgres://postgres:postgres@localhost:5432/postgres?sslmode=disable

Credentials support URI prefixes so secrets do not live in the file:

  • env://VAR — read from an environment variable.

  • file://path — read from a file.

  • literal://value — use the literal value after the prefix.

  • No prefix — used as-is.

Feature flags

The Postgres integration supports three closed feature flags. Enable only the ones you need:

  • scan — read pg_roles and pg_auth_members, then upload identities, groups, and access edges to Ploy.

  • role_management — accept tasks that add or remove memberships via GRANT/REVOKE.

  • identity_management — accept tasks that create or drop login roles.

Unknown features are rejected at startup.

Scope and filtering

The connector applies two scoping layers:

  • Reserved roles — pg_* roles are excluded automatically.

  • Include/exclude globs — you can set role_include and role_exclude patterns. Excludes always win.

Scope is delivered from the Ploy server in the startup manifest and can be adjusted without restarting the connector.

Install and run the service

Windows — install as a service from an Administrator shell:

cd "C:\Program Files\Ploy\Connector"
.\ploy-connector.exe install-service
Start-Service PloyConnector

Linux — run directly or via systemd. A sample systemd unit ships in the release tarball:

sudo systemctl enable --now ploy-connector

You can also run the binary directly for testing:

./ploy-connector -config /etc/ploy-connector/config.yaml

Verify the setup

  • Open the Ploy admin UI and go to Integrations > Connectors. Within about 30 seconds the connector should report online with a recent heartbeat.

  • On Windows, tail the log at C:\ProgramData\Ploy\Connector\logs\connector.log. On Linux, check journalctl -u ploy-connector or stdout.

  • On a healthy startup you will see connector starting, then manifest registered, then periodic scan completed lines.

Update or uninstall

Updates are drop-in replacements. Stop the service, replace the binary, and restart. Config and state persist across upgrades.

On Windows:

Stop-Service PloyConnector
Copy-Item .\ploy-connector.exe "C:\Program Files\Ploy\Connector\" -Force
Start-Service PloyConnector
Was this helpful?