@spec add_column(source(), String.t(), Lantern.SQL.column(), keyword()) ::
  :ok | {:error, String.t()}

Adds a column. column is a column spec. Returns :ok or {:error, message}.

@spec alter_column_type(source(), String.t(), String.t(), String.t(), keyword()) ::
  :ok | {:error, String.t()}

Changes a column's type. Returns :ok or {:error, message}.

@spec apply_changes(source(), String.t(), [map()], keyword()) ::
  {:ok, non_neg_integer()} | {:error, term()}

Applies update/delete changes in one database transaction.

Changes are maps with either %{action: :update, changes: map, key: map} or %{action: :delete, keys: [map]}. Returns {:ok, count} for applied change groups, or rolls the transaction back and returns the first error.

@spec columns(source(), String.t(), keyword()) ::
  {:ok, [column()]} | {:error, String.t()}

Returns column metadata (name, type, udt, nullability) for a table.

@spec create_index(source(), String.t(), String.t(), [String.t()], keyword()) ::
  :ok | {:error, String.t()}

Creates an index on a table. Returns :ok or {:error, message}.

@spec create_table(source(), String.t(), [Lantern.SQL.column()], keyword()) ::
  :ok | {:error, String.t()}

Creates a table. columns is a list of column specs (see Lantern.SQL.column/0); at least one is required.

Returns :ok or {:error, message} — both validation failures (blank name, no columns, unsupported type) and Postgres errors come back as a message string ready to show the operator.

@spec delete(source(), String.t(), [map()], keyword()) ::
  {:ok, non_neg_integer()} | {:error, term()}

Deletes one or more rows. keys is a list of %{pk_column => value} maps.

Returns {:ok, deleted_count}.

@spec drop_column(source(), String.t(), String.t(), keyword()) ::
  :ok | {:error, String.t()}

Drops a column. Returns :ok or {:error, message}.

@spec drop_constraint(source(), String.t(), String.t(), keyword()) ::
  :ok | {:error, String.t()}

Drops a table constraint. Returns :ok or {:error, message}.

@spec drop_index(source(), String.t(), keyword()) :: :ok | {:error, String.t()}

Drops an index. Returns :ok or {:error, message}.

@spec drop_table(source(), String.t(), keyword()) :: :ok | {:error, String.t()}

Drops a table. Returns :ok or {:error, message}.

@spec insert(source(), String.t(), map(), keyword()) ::
  {:ok, map()} | {:error, term()}

Inserts a row. values is a %{column => value} map (value nil → NULL).

Returns {:ok, inserted_row_map} keyed by column name.

@spec list_enums(
  source(),
  keyword()
) :: {:ok, [%{name: String.t(), values: [String.t()]}]} | {:error, String.t()}

Lists enum types in a schema. Defaults to public.

@spec list_schemas(source()) :: {:ok, [String.t()]} | {:error, String.t()}

Lists user-visible schemas that contain base tables.

@spec list_tables(
  source(),
  keyword()
) :: {:ok, [String.t()]} | {:error, String.t()}

Lists base tables in a schema. Defaults to public.

@spec list_views(
  source(),
  keyword()
) :: {:ok, [String.t()]} | {:error, String.t()}

Lists views in a schema. Defaults to public.

@spec primary_keys(source(), String.t(), keyword()) ::
  {:ok, [String.t()]} | {:error, String.t()}

Returns the ordered primary-key column names for a table (may be empty).

@spec query(source(), String.t(), keyword()) :: {:ok, map()} | {:error, String.t()}

Reads rows from table with optional filtering, sorting, and pagination.

Options

• :schema — Postgres schema/namespace. Default "public"
• :where_clause — raw SQL fragment without WHERE (operator's own DB)
• :filters — safe filter descriptors (%{column:, op:, value:}) combined with AND
• :sort_by — column name (validated against the live column list)
• :sort_dir — :asc (default) or :desc
• :limit — default 100
• :offset — default 0
• :count — :exact (default) or false to skip COUNT(*)

Returns {:ok, %{columns: [name], rows: [[value]], count: integer | nil, count_kind: atom}}.

@spec reference_options(source(), String.t(), String.t(), pos_integer(), keyword()) ::
  {:ok, [{String.t(), String.t()}]} | {:error, term()}

Returns up to limit {value, label} options from a referenced table, for rendering a foreign-key lookup. Labels prefer a human-readable column (name/title/email/…) and fall back to the referenced key itself.

@spec rename_column(source(), String.t(), String.t(), String.t(), keyword()) ::
  :ok | {:error, String.t()}

Renames a column. Returns :ok or {:error, message}.

@spec rename_table(source(), String.t(), String.t(), keyword()) ::
  :ok | {:error, String.t()}

Renames a table. Returns :ok or {:error, message}.

@spec run_query(source(), String.t(), keyword()) ::
  {:ok, map()} | {:error, String.t()}

Runs an operator-supplied SQL statement and returns its columns and rows.

This is intentionally a low-level escape hatch for trusted database workspaces. Embedders should expose it only to operators who are allowed to run arbitrary SQL against the configured connection.

@spec schema(source(), String.t(), keyword()) ::
  {:ok, %{columns: [column()], primary_keys: [String.t()], fk_options: map()}}
  | {:error, String.t()}

Loads everything Lantern.Explorer needs to display a table — columns (typed), primary keys, and pre-fetched FK lookup options — using a single Postgres connection instead of N+1.

@spec set_column_nullable(source(), String.t(), String.t(), boolean(), keyword()) ::
  :ok | {:error, String.t()}

Sets whether a column accepts NULL. Returns :ok or {:error, message}.

@spec table_info(source(), String.t(), keyword()) ::
  {:ok, table_info()} | {:error, String.t()}

Returns detailed metadata for one table.

@spec table_stats(
  source(),
  keyword()
) :: {:ok, [table_stat()]} | {:error, String.t()}

Lists base tables with total/table/index size metadata.

@spec update(source(), String.t(), map(), map(), keyword()) ::
  {:ok, map()} | {:error, term()}

Updates one row identified by its primary key.

changes is %{column => value}; key is %{pk_column => value}. Requires the table to have a primary key and key to cover it exactly.