gitlab-org--gitlab-foss/doc/development/database_query_comments.md

---
stage: Enablement
group: Database
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
---

# Database query comments with Marginalia

The [Marginalia gem](https://github.com/basecamp/marginalia) is used to add
query comments containing application related context information to PostgreSQL
queries generated by ActiveRecord.

It is very useful for tracing problematic queries back to the application source.

An engineer during an on-call incident will have the full context of a query
and its application source from the comments.

## Metadata information in comments

Queries generated from **Rails** include the following metadata in comments:

- `application`
- `controller`
- `action`
- `correlation_id`
- `line`

Queries generated from **Sidekiq** workers will include the following metadata
in comments:

- `application`
- `jid`
- `job_class`
- `correlation_id`
- `line`

Examples of queries with comments as observed in `development.log`:

1. Rails:

   ```sql
   SELECT "project_features".* FROM "project_features" WHERE "project_features"."project_id" = $1 LIMIT $2 [["project_id", 5], ["LIMIT", 1]] /*application:web,controller:jobs,action:trace,correlation_id:rYF4mey9CH3,line:/app/policies/project_policy.rb:504:in `feature_available?'*/
   ```

1. Sidekiq:

   ```sql
   SELECT "ci_pipelines".* FROM "ci_pipelines" WHERE "ci_pipelines"."id" = $1 LIMIT $2 [["id", 64], ["LIMIT", 1]] /*application:sidekiq,jid:e7d6668a39a991e323009833,job_class:ExpireJobCacheWorker,correlation_id:rYF4mey9CH3,line:/app/workers/expire_job_cache_worker.rb:14:in `perform'*/
   ```

## Enable/Disable the feature

Enabling or disabling the feature requires a **restart/SIGHUP** of the Web and
Sidekiq workers, as the feature flag's state is memoized upon starting up.

The `feature_flag` for this feature is **disabled** by default. You can enable
or disable it with:

```ruby
Feature.enable(:marginalia)
Feature.disable(:marginalia)
```