Skip to main content

Getting Started With DBGorilla SaaS

Intro​

DBGorilla is an Agentic Database Operations platform that utilizes a lightweight agent architecture to gather database and host metrics from your environment. No direct database or host access is ever required and onboarding is as simple as deploying Docker containers in your existing infrastructure.

There are two steps to get AI agents continuously monitoring your databases:

  1. Create an account.
  2. Deploy the DBGorilla Collector in your network and node_exporter on hosts to be monitored.

Account Creation​

In a browser navigate to the DBGorilla login page and select Create Account on the bottom. The name used in the Organization Name field will be shown to future users you may invite after configuring your account.

After filling in the form and selecting the Sign up button you'll be sent a verification email. Clicking the link in the email will take you back to the app and bring you to the onboarding page with information on configuring your first DBGorilla Collector.

Metrics Collection​

DBGorilla consumes metrics from customer infrastructure using the DBGorilla Collector. The collector directly consumes PostgreSQL stats and interfaces with the Prometheus node_exporter for host statistics. One instance of the collector is required per network segment and node_exporter is required on each individual database host machine you would like to monitor.

For cloud platforms like AWS RDS with no direct database host access the collector is able to consume similar metrics directly from sources like CloudWatch and node_exporter is not required.

What is the DBGorilla Collector​

The DBGorilla Collector is a custom OTEL collector that interfaces with the DBGorilla service to provide database and host metrics for your database clusters. It is provided via Docker container image and can be deployed anywhere a Linux container can be run. Configuring a collector is done via a file mounted to the container itself (provided during app onboarding immediately after sign up).

Collectors can consume metrics from one or more Components. A component is a logical database endpoint that can be a single host database server, a large cluster with many readers/writers, or a cloud database endpoint. Components added to a Collector must be network reachable by the Collector on both the database access port (e.g. 5432 for PostgreSQL) and for physical database hosts, the node_exporter port (9100 by default).

The collector requires network egress to the DBGorilla platform (otlp.dbgorilla.com and auth.dbgorilla.com) only over port 443. The DBGorilla Collector utilizes the Open Source OpenTelemetry standard for communication — Metrics are transmitted via the OpenTelemetry Protocol (OTLP) and communication between the platform and collector occurs over the Open Agent Management Protocol (OpAMP).

Example Collector Configuration​

The below collector configuration (similar to that shown during onboarding in the app) shows a simple configuration with a single DBGorilla Collector consuming metrics from one Component (a PostgreSQL cluster — db-cluster1.internal.example.com) and restricted to a single database on that component (example_db).

The Agent ID and Secret are generated per collector, while the Tenant ID identifies your Organization and is shared by all of its collectors. All three are shown during onboarding and when configuring a new collector from the application.

warning

The Secret is shown only once during initial collector configuration and is unrecoverable later. Capture it when it is displayed.

If preferred this secret (and other variables) can be passed directly to the container via environment variable and be set via your preferred secrets management pattern; the Docker command below shows both of the mentioned variables being set in this manner.

The [commands] block is not required to utilize the DBGorilla platform. When enabled, it allows the control plane to request a fixed set of read-oriented operations on your database through the Collector:

  • explain — run plan-only EXPLAIN (never EXPLAIN ANALYZE; the query is not executed)
  • execute_query — run a single SELECT (capped at 1,000 rows and a 30-second statement timeout)

If commands is disabled, the Collector has no ability to execute these operations within your infrastructure. You can further restrict which of the two are allowed with an allowed list (for example allowed = ["explain"]).

note

Any command that does run is still constrained by the privileges of the database user configured in the Collector. The Collector cannot escalate beyond that user. We recommend configuring a dedicated read-only user for the Collector.

For PostgreSQL:

CREATE USER dbg_readonly WITH PASSWORD 'replace-me';
GRANT pg_monitor TO dbg_readonly;
GRANT USAGE ON SCHEMA public TO dbg_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO dbg_readonly;
GRANT SELECT ON ALL SEQUENCES IN SCHEMA public TO dbg_readonly;
ALTER DEFAULT PRIVILEGES IN SCHEMA public
    GRANT SELECT ON TABLES TO dbg_readonly;
ALTER DEFAULT PRIVILEGES IN SCHEMA public
    GRANT SELECT ON SEQUENCES TO dbg_readonly;

Repeat the USAGE / SELECT grants for each schema you want DBGorilla to analyze. pg_monitor is needed for cluster-wide stats and topology collection; SELECT is what explain and execute_query rely on.

[dbgorilla]
domain    = "app.dbgorilla.com"
agent_id  = "a8c1cde3-3e91-4ecf-b615-26bae0c35f02"
tenant_id = "fd4c6676-c1a1-4d9a-babb-54958c26369d"
secret    = "${DBG_SERVER_SECRET}"

# One [[component]] block per database system to monitor.
[[component]]
name   = "example_db"        # the name your system will appear as in DBGorilla
engine = "postgres"

[component.provider]
type = "self_hosted"

[component.auth]
method   = "password"
user     = "dbg_readonly"
password = "${DB_PASSWORD}"

[component.connect]
host      = "db-cluster1.internal.example.com"
port      = 5432
databases = ["example_db"]   # empty = all non-template databases
ssl_mode  = "disable"        # disable | require | verify-ca | verify-full
# Use verify-full only when the collector trusts the DB server CA (mount the CA into the container if needed).

[commands]
# Optional. When enabled, allows explain and execute_query (see above).
# Disable if your security policy forbids the collector from issuing queries.
enabled = true
# allowed = ["explain"]   # optional: further restrict to a subset

Running The Collector Container​

The following Docker command shows a very simple deployment of the DBGorilla Collector directly on a Docker host. In this case both the database password and Secret are set via environment variables and the configuration file (in the current directory at name collector.toml) is mounted directly to the container as read only.

docker run --rm \
  -v "$PWD/collector.toml:/etc/dbg-collector/collector.toml:ro" \
  -e DBG_SERVER_SECRET="<secret from above>" \
  -e DB_PASSWORD="<your database password>" \
  dbgorillapublic.azurecr.io/dbg-collector:latest \
  --config-file /etc/dbg-collector/collector.toml

As the Collector is simply a Docker container it can be run in many different environments including inside of Kubernetes clusters or along with other containers via Docker Compose. For Kubernetes deployments an official Helm chart is available at oci://dbgorillapublic.azurecr.io/charts/dbg-collector and consumes the same collector.toml configuration file. The requirements remain the same regardless of environment — the configuration file must be mounted, all required variables provided, and network access must be available to your databases and their hosts (DB Connection Port + Node Exporter Port) as well as egress to the DBGorilla platform over 443.

What is node_exporter​

node_exporter is an open source Prometheus exporter that the DBGorilla collector is able to interface with in order to consume host metrics for database host servers.

The DBGorilla collector will automatically discover available node exporters running on the default port of 9100 on database hosts.

The project and related downloads can be found in its GitHub repo here: github.com/prometheus/node_exporter. It is owned by the Prometheus project and available to freely download and install.

It can be easily run via Docker with:

docker run -d \
  --net="host" \
  --pid="host" \
  -v "/:/host:ro,rslave" \
  quay.io/prometheus/node-exporter:latest \
  --path.rootfs=/host

And is also available via EPEL for RHEL based distributions.

For more detailed documentation and instructions please see the official repository linked above.

Adding Other Users to Your Organization​

After your first Collector connects and metrics begin flowing, DBGorilla is available for use immediately from the dashboard. To invite teammates: in the lower left-hand corner of the DBGorilla Dashboard click the username shown and then Admin Portal from the resulting menu — you will be taken to the Users section. From there, the green Invite User button lets you copy an invite link to send to others joining your DBGorilla Organization. This section also lets you configure roles for and deactivate users that have joined; both options appear under the Actions column for each user.