EctoEvolver

https://hexdocs.pm/ecto_evolver
Admin
EctoEvolver is a library for Elixir that provides versioned database migrations for library authors,...
Tokens:3,805
Snippets:68
Trust Score:9
Update:5 months ago
Show doc for...
Tokens:
Raw
### EctoEvolver.Version Usage

Source: https://hexdocs.pm/ecto_evolver/EctoEvolver.Version.md

Example of how to define a version migration module using EctoEvolver.Version.

```APIDOC
## `EctoEvolver.Version` Usage

### Description

Defines a module that represents a single migration step.
It provides `up/1` and `down/1` callbacks to execute SQL files.

### Options

* `:otp_app` - The OTP application containing the SQL files.
* `:version` - Version string like `"01"`, `"02"`.
* `:sql_path` - Path within `priv/` to the SQL versions directory.

### Example

```elixir
defmodule MyLibrary.Migrations.V01 do
  use EctoEvolver.Version,
    otp_app: :my_library,
    version: "01",
    sql_path: "my_library/sql/versions"
end
```

### SQL File Layout

```
priv/<sql_path>/v<version>/v<version>_up.sql
priv/<sql_path>/v<version>/v<version>_down.sql
```
```

--------------------------------

### SQL File Structure and Content

Source: https://hexdocs.pm/ecto_evolver/index.html

Organize SQL files in `priv/` and use `$SCHEMA$` as a placeholder for the schema name. Separate statements using `--SPLIT--`.

```sql
CREATE SCHEMA IF NOT EXISTS $SCHEMA$;

--SPLIT--

CREATE TABLE $SCHEMA$.my_table (
  id BIGSERIAL PRIMARY KEY,
  name TEXT NOT NULL
);
```

--------------------------------

### `up` Callback

Source: https://hexdocs.pm/ecto_evolver/EctoEvolver.Version.md

Callback function to apply the migration.

```APIDOC
## `up` Callback

### Description

Applies the migration (e.g., create tables, views).

### Signature

```elixir
@callback up(keyword()) :: :ok
```
```

--------------------------------

### build_file_path

Source: https://hexdocs.pm/ecto_evolver/EctoEvolver.SqlRunner.md

Builds the path to a SQL file for a given version and direction.

```APIDOC
## build_file_path

### Description
Builds the path to a SQL file for a given version and direction.

### Signature
```elixir
@spec build_file_path(atom(), String.t(), String.t(), :up | :down) :: String.t()
```
```

--------------------------------

### execute_sql_file

Source: https://hexdocs.pm/ecto_evolver/EctoEvolver.SqlRunner.md

Executes SQL statements from a version file with specified options.

```APIDOC
## execute_sql_file

### Description
Executes SQL statements from a version file.

### Signature
```elixir
@spec execute_sql_file(keyword()) :: :ok
```

### Options

  * `:otp_app` - The OTP app containing the `priv/` directory.
  * `:version` - Version string like `"01"`, `"02"`.
  * `:direction` - `:up` or `:down`.
  * `:sql_path` - Path within `priv/` to SQL versions directory.
  * `:prefix` - Schema prefix to substitute for `$SCHEMA$`.
  * `:adapter` - Adapter module for identifier escaping (defaults to Postgres).
```

--------------------------------

### Define a Version Module for EctoEvolver

Source: https://hexdocs.pm/ecto_evolver/index.html

Define a version module for EctoEvolver, specifying the OTP application, version string, and the path to SQL files within the `priv/` directory.

```elixir
defmodule MyLibrary.Migrations.V01 do
  use EctoEvolver.Version,
    otp_app: :my_library,
    version: "01",
    sql_path: "my_library/sql/versions"
end
```

--------------------------------

### PostgreSQL Version Tracking Comment

Source: https://hexdocs.pm/ecto_evolver/index.html

The PostgreSQL adapter uses object comments on tables to track the current migration version, enabling EctoEvolver to apply necessary upgrades.

```sql
COMMENT ON TABLE schema.my_table IS 'MyLibrary version=1';
```

--------------------------------

### EctoEvolver Adapter Callbacks

Source: https://hexdocs.pm/ecto_evolver/EctoEvolver.Adapters.Adapter.md

Defines the contract for database-specific migration operations. Adapters must implement these callbacks for version tracking and SQL escaping.

```elixir
 @callback escape_identifier(identifier :: String.t()) :: String.t()
```

```elixir
 @callback escape_string(value :: String.t()) :: String.t()
```

```elixir
 @callback get_version(
  repo :: module(),
  prefix :: String.t(),
  tracking_object :: {:view | :table | :materialized_view, String.t()}
) :: non_neg_integer()
```

```elixir
 @callback set_version(
  prefix :: String.t(),
  tracking_object :: {:view | :table | :materialized_view, String.t()},
  version :: non_neg_integer(),
  label :: String.t()
) :: :ok
```

--------------------------------

### Define a Migration Module with EctoEvolver

Source: https://hexdocs.pm/ecto_evolver/index.html

Define a module that uses EctoEvolver to manage migrations for your library. Configure OTP app, default schema prefix, version modules, and the tracking object.

```elixir
defmodule MyLibrary.Migration do
  use EctoEvolver,
    otp_app: :my_library,
    default_prefix: "my_library",
    versions: [MyLibrary.Migrations.V01],
    tracking_object: {:table, "my_main_table"}
end
```

--------------------------------

### Define EctoEvolver Migration Module

Source: https://hexdocs.pm/ecto_evolver/EctoEvolver.md

Define a migration module in your library using EctoEvolver. Specify OTP app, default prefix, ordered version modules, and the tracking object.

```elixir
defmodule MyLibrary.Migration do
  use EctoEvolver,
    otp_app: :my_library,
    default_prefix: "my_library",
    versions: [MyLibrary.Migrations.V01, MyLibrary.Migrations.V02],
    tracking_object: {:table, "my_main_table"}
end
```

--------------------------------

### get_version

Source: https://hexdocs.pm/ecto_evolver/EctoEvolver.Adapters.Adapter.md

Reads the current migrated version from the database. Returns `0` if the schema is not yet migrated.

```APIDOC
## `get_version`

### Description
Reads the current migrated version. Returns `0` if not yet migrated.

### Callback Signature
```elixir
@callback get_version(
  repo :: module(),
  prefix :: String.t(),
  tracking_object :: {:view | :table | :materialized_view, String.t()}
) :: non_neg_integer()
```
```

--------------------------------

### Generate Ecto Migration for Library

Source: https://hexdocs.pm/ecto_evolver/EctoEvolver.md

Users generate an Ecto migration that calls the library's EctoEvolver migration module for up and down operations.

```elixir
defmodule MyApp.Repo.Migrations.AddMyLibrary do
  use Ecto.Migration

  def up, do: MyLibrary.Migration.up()
  def down, do: MyLibrary.Migration.down()
end
```

--------------------------------

### resolve

Source: https://hexdocs.pm/ecto_evolver/EctoEvolver.Adapters.Adapter.md

Resolves an EctoEvolver adapter from a given Ecto adapter module.

```APIDOC
## `resolve`

### Description
Resolves an EctoEvolver adapter from an Ecto adapter module.

### Function Signature
```elixir
@spec resolve(module()) :: {:ok, module()} | {:error, :unsupported_adapter}
```
```

--------------------------------

### `down` Callback

Source: https://hexdocs.pm/ecto_evolver/EctoEvolver.Version.md

Callback function to roll back the migration.

```APIDOC
## `down` Callback

### Description

Rolls back the migration (e.g., drop tables, views).

### Signature

```elixir
@callback down(keyword()) :: :ok
```
```

--------------------------------

### set_version

Source: https://hexdocs.pm/ecto_evolver/EctoEvolver.Adapters.Adapter.md

Writes the migration version to the database after a successful migration.

```APIDOC
## `set_version`

### Description
Writes the migration version after a successful migration.

### Callback Signature
```elixir
@callback set_version(
  prefix :: String.t(),
  tracking_object :: {:view | :table | :materialized_view, String.t()},
  version :: non_neg_integer(),
  label :: String.t()
) :: :ok
```
```

--------------------------------

### Resolve EctoEvolver Adapter

Source: https://hexdocs.pm/ecto_evolver/EctoEvolver.Adapters.Adapter.md

Resolves an EctoEvolver adapter from an Ecto adapter module. Returns an {:ok, module} tuple on success or {:error, :unsupported_adapter} if the adapter is not supported.

```elixir
 @spec resolve(module()) :: {:ok, module()} | {:error, :unsupported_adapter}
```

--------------------------------

### Add ecto_evolver to Dependencies

Source: https://hexdocs.pm/ecto_evolver/index.html

Include ecto_evolver in your project's dependencies to manage database migrations.

```elixir
def deps do
  [
    {:ecto_evolver, "~> 0.1.0"}
  ]
end
```

--------------------------------

### escape_string

Source: https://hexdocs.pm/ecto_evolver/EctoEvolver.Helpers.md

Escapes a SQL string literal to prevent injection vulnerabilities.

```APIDOC
## escape_string

### Description
Escapes a SQL string literal.

### Function Signature
```elixir
@spec escape_string(String.t()) :: String.t()
```

### Examples

```elixir
iex> EctoEvolver.Helpers.escape_string("hello")
"'hello'"

iex> EctoEvolver.Helpers.escape_string("it's")
"'it''s'"
```
```

--------------------------------

### escape_string

Source: https://hexdocs.pm/ecto_evolver/EctoEvolver.Adapters.Adapter.md

Escapes a string literal for use in SQL statements.

```APIDOC
## `escape_string`

### Description
Escapes a string literal for use in SQL statements.

### Callback Signature
```elixir
@callback escape_string(value :: String.t()) :: String.t()
```
```

--------------------------------

### Escape SQL String Literal

Source: https://hexdocs.pm/ecto_evolver/EctoEvolver.Helpers.md

Escapes a SQL string literal to prevent injection vulnerabilities. Use this function when constructing raw SQL queries.

```elixir
iex> EctoEvolver.Helpers.escape_string("hello")
"'hello'"
```

```elixir
iex> EctoEvolver.Helpers.escape_string("it's")
"'it''s'"
```

--------------------------------

### escape_identifier

Source: https://hexdocs.pm/ecto_evolver/EctoEvolver.Adapters.Adapter.md

Escapes a database identifier (schema name, table name, etc.) for safe use in SQL statements.

```APIDOC
## `escape_identifier`

### Description
Escapes a database identifier (schema name, table name, etc.).

### Callback Signature
```elixir
@callback escape_identifier(identifier :: String.t()) :: String.t()
```
```
Tokens:
Raw