Setting up the CI review bot

DBGorilla reviews the database changes in your pull requests and comments on the pull request itself. It looks for things like migrations that take a heavy lock and queries that will miss an index.

How much it can see depends on whether the repository is linked to a database you have connected.

• Not linked. The review reads the pull request and nothing else. Working from the diff, it cannot tell you how big a table is, who still reads the column you are dropping, or how long a lock would hold.
• Linked. The same review, plus your live schema, query traffic and query plans from the real database.

DBGorilla never reaches into your databases for this. A collector you run inside your own network does the reading, as it does for everything else in DBGorilla. See Collector installation.

1. Install the GitHub App

The review bot is the DBGorilla GitHub App. You install it on GitHub, from either of two places that lead to the same screen:

• github.com/apps/dbgorilla/installations/new, or
• the Admin Portal in DBGorilla, under Integrations. The DBGorilla Review for GitHub card has a Connect GitHub button.

On that screen you pick the account or organization to install into, then either all repositories or a list you choose. You can change the selection on GitHub later.

The App asks for write access to repository contents, pull requests, issues and commit statuses, and read access to metadata. Writing pull requests and issues is how it posts and updates its review comments. Writing commit statuses is how it publishes its advisory check. It subscribes to one event, pull_request, and acts when a pull request is opened, reopened, marked ready for review, or updated with new commits. So pushing to a branch with an open pull request starts a fresh review of that commit.

Then come back to DBGorilla and connect the installation to your workspace from the same Integrations card. Only a workspace admin sees it. DBGorilla checks that you control the installation before linking it to your account. This is the only way an installation gets linked to a workspace. Support cannot do it for you.

The Integrations tab is enabled per account. If you do not see it, your account has not been enabled for the review bot yet. Ask DBGorilla support.

2. What a pull request looks like before the repository is linked

You do not have to finish the setup before you see anything. Once the App is installed and connected to your workspace, every pull request gets a review.

The review is one comment, updated in place on each push, headed with its verdict:

• No database risks found
• Database concerns to address
• Blocking database risk
• No database changes in this pull request

Each finding also gets an inline comment on the line it concerns, and the commit gets a status named DBGorilla Review. The status is advisory. DBGorilla does not make it a required check, so it blocks a merge only if you add it to your branch protection rules.

On a repository that is not yet linked to a database, the comment says so and tells you what to do:

Reviewed from the diff alone. Connect your database and this review checks your real schema and workloads.

To get the full review: connect your database to DBGorilla, then link this repository to that database.

Both steps are needed. Connecting a database on its own does not change the review, because the review is scoped by the repository being linked to that particular database. The rest of this page covers those two steps.

3. Connect a database

If you already have a database in DBGorilla, skip to the next step.

Connecting a database means running a collector against it. The collector runs inside your network, reads from one or more components, and reports to DBGorilla. A component is one logical database endpoint: a single server, a cluster with readers and writers, or a cloud database endpoint. The rest of DBGorilla, including this page, calls a component a database.

Follow Collector installation for your platform. A component appears in DBGorilla once the collector has sent its first topology report, not at the moment you create it.

4. Link the repository to that database

Repositories are linked per component, from the component’s own page.

1. Open the component in DBGorilla. That lands you on its Metrics tab.
2. Pick Settings from the tabs across the top.
3. Under GitHub Repositories, add the repository.

The card there explains the link: pull requests opened on a connected repository are reviewed against this component’s database.

If the card says GitHub is not connected, the App installation has not been connected to this workspace yet. Go back to step 1.

The Settings tab has no direct URL. It is only shown to workspace admins, and only when you are looking at the whole component rather than a scope within it.

The link is many to many. One component can have many repositories, and one repository can be linked to many components. A repository linked to several components is reviewed against all of them in one pass, which matters if your service writes to more than one database.

5. What the full review adds

Once the repository is linked, the review reads the diff against the database it is heading for. The reviewing agent can:

• read the current schema and configuration from the topology DBGorilla holds, instead of inferring them from migrations in the repository;
• run EXPLAIN against the real database to get a plan;
• look at the metrics, workload and activity for that component, so a claim about a table’s size or a query’s cost comes from that table and that query;
• run an ephemeral experiment to test a “what if” before recommending it.

The connected review is instructed not to make a recommendation it has not checked against one of those sources. The diff-only review has none of them, which is why it says so on every review it posts, including the clean ones.

Rate limits and credits

Reviews consume Gorilla Credits. When a workspace has used up its credits, the review comment gets a note that reviews are paused. They resume when the balance refreshes or Gorilla Credits are purchased. The note is appended; the existing review is not replaced.

There are also per-repository and per-author rate limits, set high enough that ordinary use does not reach them. Hitting one posts a note that reviews are paused and will resume automatically.

Turning it off

Three different actions turn reviews off, and they do different things.

Uninstalling the App on GitHub stops reviews at once. DBGorilla deletes the record linking that installation to your workspace.

Disconnecting the installation in the Admin Portal leaves the App installed on GitHub but deletes the same link record, so DBGorilla no longer recognises the installation and stops posting. This is also how you move an installation to a different workspace: disconnect, then connect again from the other one. An installation cannot be repointed in place.

Removing a repository from a component keeps reviews running on that repository, but they drop back to the diff-only tier.

None of these touch the comments DBGorilla has already posted. Review comments, inline comments and commit statuses on existing pull requests stay exactly as they are. If you want them gone, delete them on GitHub.