Blink.Seeder (blink v0.6.1)

View Source

The central data structure and operations for the Blink seeding pipeline.

This module provides the Seeder struct and functions for building and inserting seed data into your database.

A Seeder holds:

  • :tables — data that will be inserted into the database.
  • :table_order - the insertion order for tables.
  • :table_opts — per-table options (:batch_size, :max_concurrency) used during the copy operation.
  • :context — auxiliary data used while building the seeder, not inserted.

Summary

Types

empty()
key()
t()
table_opts()

Functions

is_key(key)
new()

Creates an empty Seeder.

run(seeder, repo, opts \\ [])

Runs the seeder, inserting all table records into the given repository. Iterates over the tables in order when seeding the database.

with_context(seeder, key, builder)

Loads context into the seeder by calling the provided builder function.

with_table(seeder, table_name, builder, opts \\ [])

Loads a table into the seeder by calling the provided builder function.

Types

empty()

@type empty() :: %Blink.Seeder{
  context: %{},
  table_opts: %{},
  table_order: [],
  tables: %{}
}

key()

@type key() :: binary() | atom()

t()

@type t() :: %Blink.Seeder{
  context: map(),
  table_opts: %{optional(key()) => table_opts()},
  table_order: [key()],
  tables: %{optional(key()) => Enumerable.t()}
}

table_opts()

@type table_opts() :: [batch_size: pos_integer(), max_concurrency: pos_integer()]

Functions

is_key(key)

(macro)

new()

@spec new() :: empty()

Creates an empty Seeder.

Example

iex> Blink.Seeder.new()
%Blink.Seeder{tables: %{}, table_order: [], table_opts: %{}, context: %{}}

run(seeder, repo, opts \\ [])

@spec run(seeder :: t(), repo :: Ecto.Repo.t(), opts :: Keyword.t()) :: :ok

Runs the seeder, inserting all table records into the given repository. Iterates over the tables in order when seeding the database.

The repo parameter must be a module that implements the Ecto.Repo behaviour and is configured with a Postgres adapter (e.g., Ecto.Adapters.Postgres).

Data stored in the Seeder's context is ignored.

Options

  • :timeout - The time in milliseconds to wait for the transaction to complete. Defaults to 15,000 (15 seconds). Set to :infinity to disable the timeout.

The following options are specific to Blink.Adapter.Postgres:

  • :batch_size - Number of rows per batch (default: 8,000). Can be overridden per-table via with_table/4.
  • :max_concurrency - Maximum number of parallel database connections for COPY operations (default: 6). Set to 1 for sequential execution. Can be overridden per-table via with_table/4.

Returns

  • :ok - When all tables have been seeded successfully

Raises an exception when the seeding operation fails.

Examples

# With custom timeout
run(seeder, MyApp.Repo, timeout: 60_000)

# Disable timeout entirely
run(seeder, MyApp.Repo, timeout: :infinity)

# With custom batch size and concurrency
run(seeder, MyApp.Repo, batch_size: 5_000, max_concurrency: 4)

with_context(seeder, key, builder)

@spec with_context(
  seeder :: t(),
  key :: key(),
  builder :: (seeder :: t(), key :: key() -> any())
) :: t()

Loads context into the seeder by calling the provided builder function.

The builder function should take a seeder and key and return the context data.

with_table(seeder, table_name, builder, opts \\ [])

@spec with_table(
  seeder :: t(),
  table_name :: key(),
  builder :: (seeder :: t(), table_name :: key() -> Enumerable.t()),
  opts :: Keyword.t()
) :: t()

Loads a table into the seeder by calling the provided builder function.

The builder function should take a seeder and table name and return an enumerable (list or stream) of maps representing the table data.

Options

The following options are specific to Blink.Adapter.Postgres:

  • :batch_size - Number of rows per batch. Overrides :batch_size in run/3.
  • :max_concurrency - Number of maximum parallel database connections. Overrides :max_concurrency in run/3.

Examples

# Without options (uses options from `run/3`)
Seeder.with_table(seeder, "users", &table/2)

# With custom batch size and concurrency
Seeder.with_table(seeder, "users", &table/2, batch_size: 1_000, max_concurrency: 2)