Before you start
- gitlab.com, or your own GitLab server at version 15.5 or newer. dbtempo refuses an older server and names the version it needs.
- The server must be reachable from the internet, with a certificate from a public certificate authority. A GitLab that is reachable only inside a private network or over a VPN is not supported yet.
- A GitLab role on each project you add: at least Reporter to read its code, Developer to open merge requests, and Maintainer for dbtempo to hear about each push.
Create a token
dbtempo connects to GitLab with an access token you create and paste in. On a free gitlab.com account, create a personal access token. On a paid plan or your own server, create a project or group access token, so the connection does not depend on one person.
| Access | Token scopes | What dbtempo can do |
|---|---|---|
| Read only | read_api and read_repository | Reads your code to match slow queries to the code that sends them. Your projects are re-read on a schedule, not on every push. |
| Read and write | api | Everything read only does, and also opens draft merge requests with fixes. Adds a webhook to each project where its role allows, so pushes are picked up as they happen. |
Connect the server and add projects
- Open Settings → Git connections. Select Connect GitLab.
- Enter the server and token. Keep
https://gitlab.comor enter your own server's address in GitLab server, paste the token into Access token, choose Read only or Read and write, and optionally give the connection a name. - Connect. Select Connect GitLab. dbtempo checks the server's version and the token's scopes before it saves anything, and says plainly what to fix when a check fails. You can connect more than one GitLab server.
- Add projects. Open the project's Sources, select Add a repository, open the GitLab tab, and select Add beside each GitLab project to index.
- Check how it stays up to date. Open the repository from the project's Sources. Its Updates line says whether it updates on every push or on a schedule. When dbtempo has a webhook on the project, Re-check asks GitLab again after you fix it.
What dbtempo reads, writes and keeps
- The token is stored encrypted and is never shown again after you save it. dbtempo uses it only to call your GitLab server.
- Your code is read by dbtempo's servers from your GitLab server. dbtempo keeps the database statements it finds and where they are in your code, not a copy of your repository. See Where your data goes for how source snippets are used in analysis.
- Writes happen only in read and write mode: a webhook on each project where the token's role allows, and a draft merge request on a new branch when you open one or allow them to open automatically. You review and merge it; dbtempo never merges. A read-only connection never opens merge requests.
- dbtempo does not edit CI configuration or certain sensitive files. When a fix would touch one, it says so instead of opening a merge request.
Replace an expiring token
Settings → Git connections shows a warning on the connection as its token's expiry date approaches. When GitLab stops accepting the token, the connection says Needs a new token.
- Create a new token. Use the same kind and scopes as before. Replace a personal token with one from the same GitLab user, and a project or group token with another project or group token.
- Replace it. Select Replace token on the connection and paste the new token. The repositories and their scan results stay.
Disconnect
Select Disconnect on the connection in Settings → Git connections. This removes the connection and every repository connected through it, with their scan results, from every project that uses them. It cannot be undone.
Disconnecting does not change anything on your GitLab server. Revoke the token in GitLab, and delete any dbtempo webhook from the project's webhook settings, if you no longer want them.
Limits
- A read-only connection, or a project whose token cannot add a webhook, updates on a schedule. A recent push can take a while to show up.
- For a very large account, the project list shows the first 5,000 projects and says so.
- dbtempo does not detect the language and framework of a GitLab project yet. Choose them in the repository's dialog.
- A GitLab server on a private network is not supported yet.