EctoDatabaseFirst

EctoDatabaseFirst is a database-first scaffolding library for Ecto projects. It introspects an existing PostgreSQL schema and generates:

• Ecto schemas
• context modules
• optional snapshot migrations
• a scaffold report with architecture guidance

The focus is not just code generation. The generator also analyzes the schema and adds practical warnings about naming, missing indexes, oversized tables, and join-table patterns so the output is easier to maintain.

Installation

Add the dependency to your mix.exs:

def deps do
  [
    {:ecto_database_first, "~> 0.1.0"},
    {:postgrex, "~> 0.20"}
  ]
end

Usage

Programmatic API:

EctoDatabaseFirst.scaffold(
  otp_app: :my_app,
  base_module: MyApp,
  namespace: "DatabaseFirst",
  repo_module: MyApp.Repo,
  output_path: ".",
  database: [
    hostname: "localhost",
    port: 5432,
    username: "postgres",
    password: "postgres",
    database: "my_app_dev",
    schema: "public"
  ]
)

Mix task:

mix ecto_database_first.scaffold \
  --otp-app my_app \
  --repo-module MyApp.Repo

Application config is also supported, which lets the consuming project keep the scaffold setup in config/config.exs and only override specific values from the CLI when needed:

config :my_app, EctoDatabaseFirst,
  base_module: MyApp,
  namespace: "DatabaseFirst",
  repo_module: MyApp.Repo,
  output_path: ".",
  report_path: "scaffold_report.md",
  include_migrations?: true,
  database: [
    hostname: "localhost",
    port: 5432,
    username: "postgres",
    password: "postgres",
    database: "my_app_dev",
    schema: "public"
  ]

With that in place, the task can run with just:

mix ecto_database_first.scaffold

If the app already defines an Ecto repo in config/config.exs, the scaffold task can read database credentials directly from the repo configuration. This is especially helpful for apps that already have:

config :my_app, :ecto_repos, [MyApp.Repo]

config :my_app, MyApp.Repo,
  database: "my_app_dev",
  username: "postgres",
  password: "postgres",
  hostname: "localhost",
  port: 5432

When multiple repos are configured, pick one explicitly with --repo-module or set repo_module: in the EctoDatabaseFirst config block.

If you want the command-line options to be saved back into config/config.exs for future runs, use:

mix ecto_database_first.scaffold --persist-config true

Generated output includes code comments and a scaffold_report.md file to help developers understand the design decisions and follow-up improvements.

By default, generated code is placed under a dedicated namespace and folder such as MyApp.DatabaseFirst and lib/my_app/database_first/... so it does not overwrite hand-written schemas or contexts in the main application namespace.

The writer is also conservative by default and refuses to overwrite existing files unless you pass:

mix ecto_database_first.scaffold --overwrite true

Design Notes

• Schemas stay focused on fields, associations, and changesets.
• Context modules own Repo interaction.
• Tables are grouped into contexts conservatively to avoid fat contexts.
• Snapshot migrations are optional and primarily useful as a baseline export.

Publishing

This project is structured as a standard Mix library and includes Hex package metadata in mix.exs, so it can be published and installed like other Elixir libraries.