Migrations

This section is based on Jennifer Docs.

To generate a migration run crystal src/sam.cr generate:migration your_migration_name

Migration DSL

The generator will create template file for you with a consistent name pattern timestamp_migration_name.cr. The empty file looks like this:

class YourCamelcasedMigrationName20170119011451314 < Jennifer::Migration::Base
  def up
  end

  def down
  end
end

The up method is where your database changes go, whereas, down is used for reverting your changes back.

Example for creating table:

create_table(:addresses) do |t|
  t.reference :contact # creates field contact_id with Int type and allows null values
  t.string :street, {:size => 20, :sql_type => "char"} # creates string field with CHAR(20) db type
  t.bool :main, {:default => false} # sets false as default value
end

Data Types and Mappings

Also if you use PostgreSQL array types are available a well: Array(Int32), Array(Char), Array(Float32), Array(Float64),Array(Int16), Array(Int32), Array(Int64), Array(String).

All of them accepts additional options:

:sql_type- gets exact (except size) field type;
:null- represent nullable if field (by default isfalsefor all types and field);
:primary- marks field as primary key field (could be several ones but this provides some bugs with query generation for such model - for now try to avoid this).
:default- default value for field
:auto_increment- marks field to use auto increment (properly works only withInt32fields, another crystal types have cut functionality for it);
:array- mark field to be array type (Postgres only)

Also there is#fieldmethod which allows to directly define sql type (very suitable for enums in Postgres).

To drop table just write

drop_table(:addresses) # drops if exists

To alter existing table use next methods:

#change_column(name, [new_name], options)- to change column definition; Postgres has slighly another implementation of this than mysql one - check source code for details;
#add_column(name, type, options)- add new column;
#drop_column(name)- drops existing column
#add_index(name : String, field : Symbol, type : Symbol, order : Symbol?, length : Int32?)- adds new index (Postgres doesn't support length parameter and only support:uniquetype);
#drop_index(name : String)- drops existing index;
#rename_table(new_name)- renames table.

Also next support methods are available:

#table_exists?(name)
#index_exists?(table, name)
#column_exists?(table, name)
#data_type_exists?(name)for Postgres ENUM

Also plain SQL could be executed as well:

execute("ALTER TABLE addresses CHANGE street st VARCHAR(20)")

All changes are executed one by one so you also could add data changes here (inupmethod) but if execution ofupmethod fails -downmethod will be called and all process will stop - be ready for such behavior.

To be sure that your db is up to date before run tests of your application, add:

Jennifer::Migration::Runner.migrate

Enum

Now enums are supported as well but it has different implementation for adapters. For mysql is enough just write down all values:

create_table(:contacts) do |t|
  t.enum(:gender, values: ["male", "female"])
end

Postgres provide much more flexible and complex behavior. Using it you need to create it firstly:

create_enum(:gender_enum, ["male", "female"])
create_table(:contacts) do |t|
  t.string :name, {:size => 30}
  t.integer :age
  t.field :gender, :gender_enum
  t.timestamps
end
change_enum(:gender_enum, {:add_values => ["unknown"]})
change_enum(:gender_enum, {:rename_values => ["unknown", "other"]})
change_enum(:gender_enum, {:remove_values => ["other"]})

For more details check source code and PostgreSQL docs.