Dumper

Takes your data and dumps it to the screen!

Dumper uses reflection to find all your app's ecto schemas and provide routes to browse their data. It's packaged as a Live Dashboard plugin for easy navigation.

Requirements

Dumper only works with Phoenix 1.7+ applications that use Ecto.

About

Dumper aims to make it as easy as possible for everyone on a project to access and understand its data.

• All ids can be linked, so it's an incredibly fast way to explore a data model against real data.
• Because it's implemented with reflection, it automatically covers every schema module in your project.
• Styling is kept consistent with the LiveDashboard theme so that data is front and center.
• Associations are also shown for a given record, all on the same page.
• Non-intrusive. No changes necessary to existing modules/files.
• Read-only. No accidentally deleting or editing data while browsing.
• Shareable URLs. Having a shareable link to every record in your database is very useful for debugging. It gives everyone including non-technical teammates the ability to get a better understanding of your data model.

Installation and Usage

Add dumper to your list of dependencies in mix.exs:

def deps do
  [
    {:dumper, "~> 0.2.5"}
  ]
end

Install and configure Phoenix Live Dashboard if you haven't already. Then modify router.ex to include the dumper as a plugin:

live_dashboard "/dashboard", additional_pages: [dumper: {Dumper.LiveDashboardPage, repo: MyApp.Repo}]

By default, Dumper will auto-discover all Ecto schemas associated with the provided repo's otp_app. You can override this behavior by explicitly passing an app as an option with otp_app: :my_app.

You can now run your web app, navigate to dumper tab within the live dashboard, and view all your data.

Customization

Config Module

It is highly recommended to customize the dumper. To do so, you can optionally define a module that implements the Dumper.Config behavior. Add it to the live_dashboard entry in your router.ex file:

live_dashboard "/dashboard", additional_pages:
  [dumper: {Dumper.LiveDashboardPage, repo: MyApp.Repo, config_module: MyApp.DumperConfig}]

Here's an example config module:

defmodule MyApp.DumperConfig do
  use Dumper.Config

  @impl Dumper.Config
  def ids_to_schema() do
    %{
      book_id: Library.Book,
      author_id: Library.Author
    }
  end

  def excluded_fields() do
    %{
      Library.Employee => [:salary, :email_address],
      Library.Book => [:price]
    }
  end

  def display(%{field: :last_name} = assigns) do
    ~H|<span style="color: red"><%= @value %></span>|
  end

  def custom_record_links(%Library.Book{} = book) do
    [
      {"https://goodreads.com/search?q=#{book.title}", "Goodreads"},
      {~p"/logging/#{book.id}", "Logs"}
    ]
  end
end

Common customizations are using the c:Dumper.Config.ids_to_schema/0 to turn id values into clickable links and using c:Dumper.Config.custom_record_links/1 to provide extra links to useful information when viewing a specific record.

Take a look a c:Dumper.Config.ids_to_schema/0, c:Dumper.Config.allowed_fields/0, c:Dumper.Config.excluded_fields/0, c:Dumper.Config.display/1, c:Dumper.Config.additional_associations/1, and c:Dumper.Config.custom_record_links/1 for more information on how each optional callback lets you customize how your data is rendered.

Other notes

Rendering Embeds

The index page and association tables on the show page by default omit columns that are embeds. This is purely for display purposes, as those values tend to take up a lot of vertical space. This is currently not configurable, but may be in the future.

Redactions

By default, schema fields with redact: true are hidden and replaced with the text redacted. If you're running the Dumper in a non-production environment or against dummy data, you may want to disregard the redacted fields. To do that, you can add a display/1 function head like the following:

def display(%{redacted: true} = assigns), do: ~H|<%= @value %>|

You can refine that down to a specific schema and/or field as well by pattern matching the assigns.

Security

As with LiveDashboard more broadly, it is highly recommended that you put the route behind some sort of admin authentication if you want to use dumper in production.

The c:Dumper.Config.allowed_fields/0 and c:Dumper.Config.excluded_fields/0callbacks are another way to be explicit about what data is shown or hidden altogether.

You could also hide the plugin altogether by modifying the live_dashboard route. For example, this would require a :dumper enabled: true config to be set in order to display the dumper tab in the live dashboard:

live_dashboard "/dashboard",
  additional_pages: [] ++ (if Application.get_env(:dumper, :enabled, false), do: [dumper: {Dumper.LiveDashboardPage, repo: MyApp.Repo}], else: [])

This would allow you to configure showing or hiding the dumper based on environments.