Inspecto (inspecto v0.3.0)

Inspecto is a utility for inspecting Ecto schemas to view their field names, data types, and default values.

Ecto schema modules do not contain full information about your database schemas: they only contain enough information to act as a viable intermediary for the Elixir layer. You cannot, for example, know character length limits or input constraints by merely inspecting Ecto schemas. Although Ecto migrations contain a lot more of this information, they too aren't great for the purpose because migrations are additive with changes spread out over time, and importantly, there's not requirement that a database be defined via migrations.

usage

Usage

The expected usage of this package is to call Inspecto.summarize/2 from within a @moduledoc tag somewhere inside your app, wherever you wish a summary of your Ecto schemas to appear, e.g. something like this:

defmodule MyApp.MyModel do
  @moduledoc """
  Here is a summary of my Ecto schemas:

  #{ MyApp.MyModel |> Inspecto.modules() |> Inspecto.summarize(format: :html)}
  """
end

This will render a series of HTML tables at compile-time.

Warning

When you call a function from inside a @moduledoc tag, it is evaluated at compile-time. Inspecto should filter out problems and avoid raising errors, but if it generates a problem for any reason, be aware that you may need to remove any calls to its functions from your @moduledoc tags.

Link to this section Summary

Functions

This is a convenience function which retrieves a list of modules in the given "namespace". This is a useful way of gathering up modules that define Ecto schemas.

Summarizes the given Ecto schema modules using the format provided.

Link to this section Functions

Link to this function

modules(namespace)

This is a convenience function which retrieves a list of modules in the given "namespace". This is a useful way of gathering up modules that define Ecto schemas.

examples

Examples

iex> Inspecto.modules(MyApp)
[MyApp.Foo, MyApp.Bar, ...]
Link to this function

summarize(modules, opts \\ [])

@spec summarize(modules :: [module()], opts :: Keyword.t()) ::
  String.t() | [Inspecto.Schema.t()]

Summarizes the given Ecto schema modules using the format provided.

It is necessary to supply a list of modules.

options

Options

  • :format controls the format of the output. Supported values: :html, :raw (default).
  • :h controls the heading level used for each schema (3 corresponds to an h3 tag). This is only relevant when :format is set to :html. Default: 2

The :raw format returns information as a list of Inspecto.Schema structs.

The :html format returns information as an HTML table. This is suitable for use inside a @moduledoc attribute.

Other formats may be supported in the future (e.g. Mermaid JS, but it's not yet compatible with how documentation generation strips out newlines).

examples

Examples

iex> MyApp.Schemas |> Inspecto.modules() |> Inspecto.summarize(format: :raw)
[
  %Inspecto.Schema{
    fields: [
      %Inspecto.Schema.Field{default: nil, name: :id, type: :binary_id},
      %Inspecto.Schema.Field{default: nil, name: :meta, type: :map},
      %Inspecto.Schema.Field{default: 30, name: :net, type: :integer},
      # ...
    ],
    module:MyApp.Schemas.SomeSchema,
    primary_key: [:id],
    source: "some_table"
  }
],
#  ...