@spec batch_create(module(), map(), keyword()) ::
  {:ok, %{succeeded: list(), failed: list(), total: non_neg_integer()}}
  | {:error, any()}

Batch creates multiple records in a single transaction.

Parameters

• schema_module - The Ecto schema module
• params - Map containing "records" key with a list of attribute maps
• opts - Options including :scope, :repo, :batch_size

Examples

batch_create(MyApp.Accounts.User, %{
  "records" => [
    %{"email" => "a@b.com", "name" => "Alice"},
    %{"email" => "b@c.com", "name" => "Bob"}
  ]
})

@spec batch_destroy(module(), map(), keyword()) ::
  {:ok, %{succeeded: list(), failed: list(), total: non_neg_integer()}}
  | {:error, any()}

Batch destroys multiple records in a single transaction.

Parameters

• schema_module - The Ecto schema module
• params - Map containing "ids" key with a list of primary key values
• opts - Options including :scope, :repo, :batch_size

Examples

batch_destroy(MyApp.Accounts.User, %{
  "ids" => [1, 2, 3]
})

@spec batch_update(module(), map(), keyword()) ::
  {:ok, %{succeeded: list(), failed: list(), total: non_neg_integer()}}
  | {:error, any()}

Batch updates multiple records in a single transaction.

Parameters

• schema_module - The Ecto schema module
• params - Map containing "records" key with a list of maps (each must include the primary key)
• opts - Options including :scope, :repo, :batch_size

Examples

batch_update(MyApp.Accounts.User, %{
  "records" => [
    %{"id" => 1, "name" => "Alice Updated"},
    %{"id" => 2, "email" => "b@new.com"}
  ]
})

Creates a new record.

Parameters

• schema_module - The Ecto schema module
• params - Map of attributes

Examples

create(MyApp.Accounts.User, %{"email" => "test@example.com", "name" => "Test"})

Deletes a record.

Parameters

• schema_module - The Ecto schema module
• params - Map containing the primary key value

Examples

destroy(MyApp.Accounts.User, %{"id" => 123})

@spec detect_repo() :: module() | nil

Detects the Repo module based on the application name.

@spec get(module(), map(), keyword()) :: {:ok, struct() | nil} | {:error, any()}

Gets a single record by primary key.

Parameters

• schema_module - The Ecto schema module
• params - Map containing the primary key value
• opts - Options including :preload for eager-loading associations

Examples

get(MyApp.Accounts.User, %{"id" => 123})
get(MyApp.Accounts.User, %{"id" => 123}, preload: [:posts, :comments])

@spec list(module(), map(), keyword()) :: {:ok, [struct()] | map()} | {:error, any()}

Lists records with optional filters.

Parameters

• schema_module - The Ecto schema module
• params - Map of filter parameters (optional)
• opts - Options including pagination

Examples

list(MyApp.Accounts.User, %{"email" => "test@example.com"}, limit: 10)

@spec repo() :: module() | nil

Gets the configured Repo module.

Returns the repo from config or attempts to detect it from the application name.

Restores a soft-deleted record by setting its soft-delete field to nil.

Parameters

• schema_module - The Ecto schema module
• params - Map containing the primary key value

Examples

restore(MyApp.Accounts.User, %{"id" => 123})

Updates an existing record.

Parameters

• schema_module - The Ecto schema module
• params - Map containing primary key and updated attributes

Examples

update(MyApp.Accounts.User, %{"id" => 123, "name" => "New Name"})

@spec upsert(module(), map(), keyword()) ::
  {:ok, {struct(), atom()}} | {:error, Ecto.Changeset.t()}

Upserts a record - inserts a new record or updates an existing one based on conflict target.

Parameters

• schema_module - The Ecto schema module
• params - Map of attributes
• opts - Options including :conflict_target and :on_conflict

Options

• :conflict_target - Field(s) to check for conflicts. Single atom or list of atoms.
• :on_conflict - What to do on conflict. :replace_all (default) or [set: [...]]

Examples

upsert(MyApp.Accounts.User, %{"email" => "test@example.com", "name" => "Test"},
  conflict_target: :email,
  on_conflict: :replace_all
)

Returns {:ok, {record, :inserted}} or {:ok, {record, :updated}}.

@spec validate_includes(list() | nil, [atom() | String.t()], keyword()) :: keyword()

Validates dynamic include requests against allowed preloadable associations.

Returns the opts keyword list with merged preloads. allowed may be a list of association atoms or strings; include entries not in the allowlist are dropped.