<commit_before>---
title: Migrations
toc: true
active: guides
template: guide-page.html
---

# Migrations

## Command Line

The `azul` command line tool can be used both to quickly create migrations as
well as to run the migrations.

To create a new migration:

```bash
$ azul make-migration create-articles
```

The migration file will be empty. You'll fill it in with schema changes that
you want to make in this migration. Once completed, you can run your migrations
with the command line tool, and roll them back as needed.

```bash
$ azul migrate
$ azul rollback
```

## Migration Basics

Migrations are sequences of changes that are made to your database schema over
time. They allow a team of developers to work together more fluidly. Each
migration is applied in the order in which it was created. It is assumed that
once created and applied, that migrations do not change. That is, once you
commit a migration and push it, you should not change it. You should instead
create a new migration.

Azul.js migrations are simply modules that export two functions, an `up`
function and a `down` function. When you migrate your database schema forward,
you'll run `azul migrate` and the `up` will be run. When you migrate your
schema backward, you'll run `azul rollback` and the `down` function will be
run. It is expected that your `down` function reverse the changes that your up
function makes.

An example migration looks like this:

```js
exports.up = function(schema) {
  schema.createTable('articles', function(table) {
    table.string('title');
    table.text('body');
  });
};

exports.down = function(schema) {
  schema.dropTable('articles');
};
```

In fact, Azul.js is able to determine how to [reverse many
migrations](#reversible-migrations). For these migrations, you'll only need to
export a `change` function. The above example is reversible and could simply be
written:

```js
exports.change = function(schema) {
  schema.createTable('articles', function(table) {
    table.string('title');
    table.text('body');
  });
};
```

For examples of running multiple actions in a single migration, see the example
migrations discussed in the [relations
documentation][azul-relations#one-to-many].

Migrations are run inside of a transaction, so if any of the migrations in a
sequence of migrations fails, the entire group will be rolled back. This is
only true if your database supports transactions.

The `up` and `down` functions are provided with a second argument. A
[basic query][azul-queries#data-queries] object that you can use if you need to
execute raw SQL or perform schema changes that are not supported by Azul.js.

Migrations support two modes of execution, _sequential_ and _manual_. The
examples given above are sequential. Each schema change will be executed
in the order they are written. In this mode, you cannot write asynchronous code
(no callbacks or promises). You therefore cannot obtain the results of any
queries. If you need full control, _manual_ mode can be enabled by simply
returning a promise or _thenable_ from the from the `up` or `down` function. In
manual mode, you are responsible for executing all queries in your migration.

## Reversible Migrations

Azul.js is able to determine the reverse of migrations that do not make
destructive changes. For instance, _creating_ a table can be reversed because
no additional information is needed to know that the reverse is to remove that
table. On the other hand, if you write a migration to drop a table, more
information would be needed to know how to re-create the table. Operations
that _rename_ will also be reversible.

Each method below will discuss in more detail whether it can be used with the
`change` function.

## Methods

### `#createTable`

Create new tables. Pass the name of the table you want to create and a callback
that will receive a table object with which you will be able to create columns
of different [field types](#methods-field-types).

```js
schema.createTable('articles', function(table) {
  table.string('title');
  table.text('body');
});
```

This method is always [_reversible_](#reversible-migrations).

Returns a _thenable_ [basic query][azul-queries#data-queries] with the
following chainable methods:

#### `#primaryKey` or `#pk`

Defines the primary key of the table. The default is `id`. Pass
`null` to create a table without a primary key. You can configure the primary
key's type or options within your table definition callback. See below for an
example.

#### `#unlessExists`

Will not create the table if it already exists.

#### `#with`

Allows delayed definition of the table columns & indexes.

```js
schema.createTable('articles')
.pk('identifier')
.unlessExists()
.with(function(table) {
   table.serial('identifier').notNull(); // pk
   table.string('title');
});
```

#### `table#index(columns, [options])`

Add an index to the table.

```js
table.index('boss_id'); // name automatically set to boss_id_idx
table.index(['first_name', 'last_name'], { name: 'full_name_index' });
```


### `#alterTable`

Alter existing tables. Pass the name of the table you want to alter and a
callback that will receive a table object with which you will be able to
create columns of different [field types](#methods-field-types) as
well as drop existing columns.

```js
schema.alterTable('articles', function(table) {
  table.string('title'); // add a title column
  table.drop('body'); // drop the body column
});
```

This method is [_reversible_](#reversible-migrations) unless you
[`drop`](#methods-altertable-table-drop) a column.


#### `table#index(columns, [options])`

Add an index to the table. See
[create table examples](#methods-createtable-table-index).

#### `table#rename`

Renames a table column.

While not intuitive, a third argument, `type`, is required for a rename. This
is because certain backends need this value in order to perform a rename. The
value of the type _must match_ the type used to create the column.

```js
schema.alterTable('articles', function(table) {
  table.rename('title', 'headline', 'string'); // rename the title column
});
```

#### `table#drop`

Drops a table column.

```js<commit_msg>Added docs for field so all methods are documented.<commit_after>---
title: Migrations
toc: true
active: guides
template: guide-page.html
---

# Migrations

## Command Line

The `azul` command line tool can be used both to quickly create migrations as
well as to run the migrations.

To create a new migration:

```bash
$ azul make-migration create-articles
```

The migration file will be empty. You'll fill it in with schema changes that
you want to make in this migration. Once completed, you can run your migrations
with the command line tool, and roll them back as needed.

```bash
$ azul migrate
$ azul rollback
```

## Migration Basics

Migrations are sequences of changes that are made to your database schema over
time. They allow a team of developers to work together more fluidly. Each
migration is applied in the order in which it was created. It is assumed that
once created and applied, that migrations do not change. That is, once you
commit a migration and push it, you should not change it. You should instead
create a new migration.

Azul.js migrations are simply modules that export two functions, an `up`
function and a `down` function. When you migrate your database schema forward,
you'll run `azul migrate` and the `up` will be run. When you migrate your
schema backward, you'll run `azul rollback` and the `down` function will be
run. It is expected that your `down` function reverse the changes that your up
function makes.

An example migration looks like this:

```js
exports.up = function(schema) {
  schema.createTable('articles', function(table) {
    table.string('title');
    table.text('body');
  });
};

exports.down = function(schema) {
  schema.dropTable('articles');
};
```

In fact, Azul.js is able to determine how to [reverse many
migrations](#reversible-migrations). For these migrations, you'll only need to
export a `change` function. The above example is reversible and could simply be
written:

```js
exports.change = function(schema) {
  schema.createTable('articles', function(table) {
    table.string('title');
    table.text('body');
  });
};
```

For examples of running multiple actions in a single migration, see the example
migrations discussed in the [relations
documentation][azul-relations#one-to-many].

Migrations are run inside of a transaction, so if any of the migrations in a
sequence of migrations fails, the entire group will be rolled back. This is
only true if your database supports transactions.

The `up` and `down` functions are provided with a second argument. A
[basic query][azul-queries#data-queries] object that you can use if you need to
execute raw SQL or perform schema changes that are not supported by Azul.js.

Migrations support two modes of execution, _sequential_ and _manual_. The
examples given above are sequential. Each schema change will be executed
in the order they are written. In this mode, you cannot write asynchronous code
(no callbacks or promises). You therefore cannot obtain the results of any
queries. If you need full control, _manual_ mode can be enabled by simply
returning a promise or _thenable_ from the from the `up` or `down` function. In
manual mode, you are responsible for executing all queries in your migration.

## Reversible Migrations

Azul.js is able to determine the reverse of migrations that do not make
destructive changes. For instance, _creating_ a table can be reversed because
no additional information is needed to know that the reverse is to remove that
table. On the other hand, if you write a migration to drop a table, more
information would be needed to know how to re-create the table. Operations
that _rename_ will also be reversible.

Each method below will discuss in more detail whether it can be used with the
`change` function.

## Methods

### `#createTable`

Create new tables. Pass the name of the table you want to create and a callback
that will receive a table object with which you will be able to create columns
of different [field types](#methods-field-types).

```js
schema.createTable('articles', function(table) {
  table.string('title');
  table.text('body');
});
```

This method is always [_reversible_](#reversible-migrations).

Returns a _thenable_ [basic query][azul-queries#data-queries] with the
following chainable methods:

#### `#primaryKey` or `#pk`

Defines the primary key of the table. The default is `id`. Pass
`null` to create a table without a primary key. You can configure the primary
key's type or options within your table definition callback. See below for an
example.

#### `#unlessExists`

Will not create the table if it already exists.

#### `#with`

Allows delayed definition of the table columns & indexes.

```js
schema.createTable('articles')
.pk('identifier')
.unlessExists()
.with(function(table) {
   table.serial('identifier').notNull(); // pk
   table.string('title');
});
```

#### `table#field(column, [options])`

Create a column of the type given by `field`. See
[field types](#methods-field-types) for a comprehensive list of types, options,
and examples.

#### `table#index(columns, [options])`

Add an index to the table.

```js
table.index('boss_id'); // name automatically set to boss_id_idx
table.index(['first_name', 'last_name'], { name: 'full_name_index' });
```


### `#alterTable`

Alter existing tables. Pass the name of the table you want to alter and a
callback that will receive a table object with which you will be able to
create columns of different [field types](#methods-field-types) as
well as drop existing columns.

```js
schema.alterTable('articles', function(table) {
  table.string('title'); // add a title column
  table.drop('body'); // drop the body column
});
```

This method is [_reversible_](#reversible-migrations) unless you
[`drop`](#methods-altertable-table-drop) a column.

#### `table#field(column, [options])`

Create a column of the type given by `field`. See
[field types](#methods-field-types) for a comprehensive list of types, options,
and examples.

#### `table#index(columns, [options])`

Add an index to the table. See
[create table examples](#methods-createtable-table-index).

#### `table#rename`

Renames a table column.

While not intuitive, a third argument, `type`, is required for a rename. This
is because certain backends need this value in order to perform a rename. The
value of the type _must match_ the type used to create the column.

```js
schema.alterTable('articles', function(table) {
  table.rename('title', 'headline', 'string'); // rename the title column
});
```

#### `table#drop`

Drops a table column.

```js
{'fraction_non_alphanumeric': 0.09362002668131524, 'fraction_numerical': 0.0, 'mean_word_length': 4.591926283457657, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6322538', 'n_tokens_mistral': 3583, 'n_tokens_neox': 3446, 'n_words': 1715}