{"id":28968571,"url":"https://github.com/culturehq/rack-queries","last_synced_at":"2025-08-21T10:16:49.686Z","repository":{"id":38361075,"uuid":"172792385","full_name":"CultureHQ/rack-queries","owner":"CultureHQ","description":"A page in your rack-based application that allows quick execution of pre-built queries","archived":false,"fork":false,"pushed_at":"2023-01-24T10:03:20.000Z","size":4126,"stargazers_count":24,"open_issues_count":29,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-05-20T16:55:20.669Z","etag":null,"topics":["rack","react"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CultureHQ.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-02-26T21:20:26.000Z","updated_at":"2024-02-28T10:45:48.000Z","dependencies_parsed_at":"2023-02-13T20:02:01.120Z","dependency_job_id":null,"html_url":"https://github.com/CultureHQ/rack-queries","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/CultureHQ/rack-queries","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CultureHQ%2Frack-queries","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CultureHQ%2Frack-queries/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CultureHQ%2Frack-queries/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CultureHQ%2Frack-queries/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CultureHQ","download_url":"https://codeload.github.com/CultureHQ/rack-queries/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CultureHQ%2Frack-queries/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261641028,"owners_count":23188434,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["rack","react"],"created_at":"2025-06-24T09:09:20.670Z","updated_at":"2025-06-24T09:09:37.642Z","avatar_url":"https://github.com/CultureHQ.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Rack::Queries\n\n[![Build Status](https://github.com/CultureHQ/rack-queries/workflows/Main/badge.svg)](https://github.com/CultureHQ/rack-queries/actions)\n[![Gem Version](https://img.shields.io/gem/v/rack-queries.svg)](https://github.com/CultureHQ/rack-queries)\n\nThis gem provides a page in your rack-based (e.g., `Rails`, `Sinatra`) application that allows quick execution of pre-built queries. The goal is to allow quick insights into the state of your application without needing to update the main UI. Consider it a backdoor admin page that you can use before you decide to truly expose query results.\n\n![Screenshot](docs/screenshot.png)\n\n## Usage\n\nFirst, add `rack-queries` to your Gemfile and `bundle install`. Then, mount the `Rack::Queries::App` application within your app.\n\nWithin Rails, that will look like (within `config/routes.rb`):\n\n```ruby\nRails.application.routes.draw do\n  mount Rack::Queries::App, at: '/queries'\nend\n```\n\nThen, you can go to `/queries` within your application to view the empty queries page.\n\nSecond, define the queries that you want included on your query page. Queries are classes that respond to `run(opts)`. The `run` method should return either a single value or an array of arrays (in the UI it will either display one value or a table). The following example returns an overall count:\n\n```ruby\nclass UserCountQuery\n  def run(_opts)\n    User.count\n  end\nend\n```\n\nIf you want your queries to have arguments (say for instance that users can be scoped to organizations), you define public instance methods on your query class:\n\n```ruby\nclass UserPerOrgCountQuery\n  def org\n    Org.order(:name).pluck(:name)\n  end\n\n  def run(opts)\n    Org.where(name: opts['org']).users.count\n  end\nend\n```\n\nEach public instance method is expected to return an array of options (they get transformed into `select` tags in the UI). They are then given to the `run` method through the `opts` hash which contains the value within a string key corresponding to the method name.\n\nFinally, inform `rack-queries` that you want to include the query on your query page by adding it to the list:\n\n```ruby\nRack::Queries.add(\n  UserCountQuery,\n  UserPerOrgCountQuery\n)\n```\n\n### Customization\n\nQuery objects can optionally have a bit of customization with regard to display through the `::name` and `::desc` methods. Overriding the `::name` method will change the display on the right-hand side, and adding a `::desc` method will add a small paragraph with a description below the name.\n\n### Query DSL\n\nYou can create queries manually as described above, or you can use a minimal DSL through the `Rack::Queries::create` method. To recreate the `UserPerOrgCountQuery` as above, you could:\n\n```ruby\nRack::Queries.create do\n  name 'UserPerOrgCountQuery'\n  desc 'The count of users in each organization'\n\n  opt :org do\n    Org.order(:name).pluck(:name)\n  end\n\n  run do |opts|\n    Org.where(name: opts['org']).users.count\n  end\nend\n```\n\nWith the DSL, you can additionally provide a `type` for your options that allows them to be specified on the client side. By default, the type is `select`, which will perform a query to the server to get the list of options. However, if you specify one of the other types (`string` or `text`), it will instead allow the user to provide input. For example, to allow a text area field, you would:\n\n```ruby\nRack::Queries.create do\n  name 'Some CSV parsing'\n  desc 'Parse some CSV input!'\n\n  opt :csv, type: :text\n\n  run do |opts|\n    require 'csv'\n\n    CSV.foreach(opts['csv']) do\n      ...\n    end\n\n    ...\n  end\nend\n```\n\n### Middleware\n\nSince `Rack::Queries` is a rack application, you can add whatever middleware you like into its stack before the request hits the application. For instance, to integrate HTTP basic auth around it to protect the query results, you can use the `Rack::Queries::App::use` method as in:\n\n```ruby\nRack::Queries::App.use(Rack::Auth::Basic) do |username, password|\n  compare = lambda { |left, right|\n    ActiveSupport::SecurityUtils.secure_compare(\n      ::Digest::SHA256.hexdigest(left),\n      ::Digest::SHA256.hexdigest(right)\n    )\n  }\n\n  credentials = Rails.application.credentials\n\n  compare[username, credentials.rack_queries_username] \u0026\n    compare[password, credentials.rack_queries_password]\nend\n```\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/CultureHQ/rack-queries.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fculturehq%2Frack-queries","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fculturehq%2Frack-queries","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fculturehq%2Frack-queries/lists"}