Repodb.Migration

repodb · API reference

type default_expr = 
  | Raw of string
  | Current_timestamp
  | Null
  | Bool of bool
  | Int of int
  | Int64 of int64
  | Float of float
  | Text of string

Declarative database migrations and migration planning.

A migration has a monotonically increasing version, a human-readable name, and lists of up and down operations. Repodb can render those operations for PostgreSQL, SQLite, MySQL/MariaDB, or the generic dialect used by tests.

Example:

let create_users =
    Migration.migration ~version:20260101120000L ~name:"create_users"
      ~up:
        [ Migration.create_table "users"
            [ Migration.typed_column "id" Types.int64
                ~primary_key:true ~nullable:false;
              Migration.typed_column "email" Types.string
                ~nullable:false ~unique:true;
              Migration.typed_column "inserted_at" Types.ptime
                ~nullable:false
                ~default_expr:Migration.Current_timestamp
            ] ]
      ~down:[ Migration.drop_table "users" ]

Use typed_column when the column maps to a Types.t; use column with an explicit SQL type for backend-specific types. Prefer structured default expressions over Raw when possible.

Planning functions compare available migrations with already-applied versions and return ordered actions. This separates migration planning from execution so CLIs can print dry-runs, apply targets, or rollback a fixed number of steps before touching the database.

type column_type = 
  | RawType of string
  | Typed : 'a Types.t -> column_type

type fk_action = 
  | Cascade
  | Restrict
  | Set_null
  | Set_default
  | No_action

type column_def = {
  col_name : string;
  col_type : column_type;
  col_nullable : bool;
  col_primary_key : bool;
  col_unique : bool;
  col_default : default_expr option;
  col_references : (string * string) option;
  col_on_delete : fk_action option;
  col_on_update : fk_action option;
}

type index_def = {
  idx_name : string option;
  idx_table : string;
  idx_columns : string list;
  idx_unique : bool;
}

type operation = 
  | Create_table of {
    name : string;
    columns : column_def list;
  }
  | Drop_table of string
  | Alter_table of {
    name : string;
    changes : alter_change list;
  }
  | Create_index of index_def
  | Drop_index of string
  | Execute of string

and alter_change = 
  | Add_column of column_def
  | Drop_column of string
  | Rename_column of {
    from : string;
    to_ : string;
  }
  | Alter_column of {
    name : string;
    new_type : string option;
    new_nullable : bool option;
  }

type t = {
  version : int64;
  name : string;
  up : operation list;
  down : operation list;
}

val default_expr_of_args : 
  default_expr:default_expr option ->
  default:string option ->
  default_expr option

val make_column : 
  ?nullable:bool ->
  ?primary_key:bool ->
  ?unique:bool ->
  ?default:string ->
  ?default_expr:default_expr ->
  ?references:(string * string) ->
  ?on_delete:fk_action ->
  ?on_update:fk_action ->
  col_type:column_type ->
  string ->
  column_def

val column : 
  ?nullable:bool ->
  ?primary_key:bool ->
  ?unique:bool ->
  ?default:string ->
  ?default_expr:default_expr ->
  ?references:(string * string) ->
  ?on_delete:fk_action ->
  ?on_update:fk_action ->
  string ->
  string ->
  column_def

val typed_column : 
  ?nullable:bool ->
  ?primary_key:bool ->
  ?unique:bool ->
  ?default:string ->
  ?default_expr:default_expr ->
  ?references:(string * string) ->
  ?on_delete:fk_action ->
  ?on_update:fk_action ->
  string ->
  'a Types.t ->
  column_def

val create_table : string -> column_def list -> operation

val drop_table : string -> operation

val add_column : column_def -> alter_change

val drop_column : string -> alter_change

val rename_column : from:string -> to_:string -> alter_change

val alter_table : string -> alter_change list -> operation

val create_index : 
  ?unique:bool ->
  ?name:string ->
  string ->
  string list ->
  operation

val drop_index : string -> operation

val execute : string -> operation

val timestamps : unit -> column_def list

val migration : 
  version:int64 ->
  name:string ->
  up:operation list ->
  down:operation list ->
  t

val render_default_expr : dialect:Driver.dialect -> default_expr -> string

val column_type_to_sql : dialect:Driver.dialect -> column_type -> string

val fk_action_to_sql : fk_action -> string

val column_to_sql_dialect : dialect:Driver.dialect -> column_def -> string

val column_to_sql : column_def -> string

val operation_to_sql_dialect : dialect:Driver.dialect -> operation -> string

val operation_to_sql : operation -> string

val schema_migrations_table : operation

val create_schema_migrations_sql_dialect : dialect:Driver.dialect -> string

val create_schema_migrations_sql : string

val placeholder_for_dialect : Driver.dialect -> int -> string

val insert_migration_sql_dialect : dialect:Driver.dialect -> string

val insert_migration_sql : string

val delete_migration_sql_dialect : dialect:Driver.dialect -> string

val delete_migration_sql : string

val get_applied_versions_sql : string

val get_migration_status_sql : string

type migration_status = {
  applied_versions : int64 list;
  pending : t list;
  last_applied : int64 option;
}

val sort_migrations : t list -> t list

val pending_migrations : applied_versions:int64 list -> t list -> t list

val generate_up_sql_dialect : dialect:Driver.dialect -> t -> string list

val generate_down_sql_dialect : dialect:Driver.dialect -> t -> string list

val generate_up_sql : t -> string list

val generate_down_sql : t -> string list

type migration_action = 
  | Migrate of {
    sql : string list;
    version : int64;
    name : string;
  }
  | Rollback of {
    sql : string list;
    version : int64;
  }
  | CreateSchemaTable of string
  | RecordMigration of {
    version : int64;
    name : string;
  }
  | RemoveMigration of int64

val plan_migrate_dialect : 
  dialect:Driver.dialect ->
  applied_versions:int64 list ->
  target:int64 option ->
  t list ->
  migration_action list

val plan_migrate : 
  applied_versions:int64 list ->
  target:int64 option ->
  t list ->
  migration_action list

val plan_rollback_dialect : 
  dialect:Driver.dialect ->
  applied_versions:Int64.t list ->
  step:int option ->
  t list ->
  migration_action list

val plan_rollback : 
  applied_versions:Int64.t list ->
  step:int option ->
  t list ->
  migration_action list

val action_to_sql : migration_action -> string list

val actions_to_sql : migration_action list -> string list

val format_status : applied_versions:int64 list -> migrations:t list -> string