Skip to content

Adding Columns

Jump to bottom
Azema edited this page Jan 1, 2012 · 11 revisions

Adding columns to database tables

Version française voir plus bas.

Introduction

The migration framework delegates all operations to your RDBMS-specific adapter, which creates the exact SQL needed for your RDMBS.

Because migrations are portable across RDMBSs, the definitions for tables and columns need to be expressed in a higher-level "language", and not RDBMS-specific SQL.

This page documents the syntax for adding and modifying columns in your database.

Details

All columns in a database are really just specific types of a generalized form. That is, a varchar(32) column is really just a string that happens to have a max-length of 32. Same for int(8), its just a number with a maximum value of 99999999.

The framework can take advantage of this fact to offer generalized types (with sane defaults) and the support for specifying exact details.

NOTE: The documentation below for adding columns is the same whether you are adding a column via a TableDefinition result object (using the column() method on the result object of a create_table()) or directly using the add_column() method.

For MySQL, the supported types are:

All column types have defaults with support for specifying details. For example, all columns declared as string will default to 255 characters.

Lets get started with some examples already!

Default assumptions All column definitions start out with some default assumptions, which you can override as needed.

  • Columns are NULL by default

Lets see an example to get started (all examples below, assume that $users is the result of calling $this->create_table("users");):

Example A:

Create a column called first_name with a default length of 255:

   $users->column("first_name", "string");

This generates the SQL:

    `first_name` varchar(255) NULL

Example B: Create a column called first_name with a max-length of 32 ( implicitly allow NULL values):

    $users->column("first_name", "string", array('limit' => 32));

This generates the SQL:

    `first_name` varchar(32) NULL

Example C: Create a column called first_name with a max-length of 64, a default value of 'mr.' and do not allow NULL values:

    $users->column("first_name", "string", array('limit' => 64, 'default' => 'mr.', 'null' => false));

This generates the SQL:

    `first_name` varchar(64) DEFAULT 'mr.' NOT NULL

Example D: Create a numeric column called post_count with a max-length of 4 digits, a default value of 0 and NULL values not allowed:

    $users->column("post_count", "integer", array('limit' => 4, 'default' => 0, 'null' => false));

This generates the SQL:

    `post_count` integer(4) DEFAULT 0 NOT NULL

Example E: Create a datetime column called created_at and NULL values not allowed:

    $users->column("created_at", "datetime", array('null' => false));

This generates the SQL:

    `created_at` datetime NOT NULL

Example F: Specify your own key primary key. By default the framework will generate an 'id' column as a primary key, but if you would like to specify your own primary key column pass a value of Boolean true into the 'primary_key' option. This requires that you in turn specify 'id' => false into the create_table options.

    $t = $this->create_table('users', array('id' => false, 'options' => 'Engine=InnoDB'));
    $t->column('guid', 'string', array('primary_key' => true));
    $t->finish();

French

Ajout de colonnes aux tables de la base

Introduction

Le framework de migration délègue toutes les opérations à l'adaptateur de votre RDBMS, qui crée le SQL exacte dont à besoin votre RDBMS.

Parce que les migrations sont portables sur RDMBSs, les définitions des tables et des colonnes doivent être exprimées dans un "langage" de niveau supérieur, et non en SQL spécifique aux RDBMS.

Cette page documente la syntaxe pour ajouter et modifier les colonnes dans votre base de données.

Details

Toutes les colonnes dans une base de données sont vraiment spécifiques à des types généralisés. Par exemple, un varchar (32) est simplement un string qui à une longueur max de 32. Idem pour int (8), c'est juste un numéro avec une valeur maximale de 99999999.

Le framework peut profiter d'offrir des types généralisés (avec les mêmes défauts) et choisir la spécification des détails exacts.

NOTE: La documentation ci-dessous pour ajouter des colonnes est la même que vous ajoutiez une colonne via l'objet TableDefinition (en utilisant la méthode column() sur l'objet retourné par create_table()) ou directement en utilisant la méthode add_column.

Pour MySQL, les types supportés sont:

Types

Tous les types de colonnes ont des valeurs par défaut pour les détails spécifiques. Par exemple, toutes les colonnes déclarées string auront par défaut une taille de 255 caractères.

Démarrons avec quelques exemples

Hypothèses des valeurs par défaut Toutes les définitions de colonne commencent avec des hypothèses par défaut, que vous pouvez modifier au besoin.

  • Colonnes ont NULL par défault

Voyons un exemple pour commencer (tous les exemples ci-dessous, on suppose que $users est le résultat de l'appel $this->create_table("users");):

Exemple A:

Créons une colonne nommée first_name avec par défaut une longueur de 255 caractères:

   $users->column("first_name", "string");

Ce qui génère le SQL:

    `first_name` varchar(255) NULL

Exemple B: Créons une colonne nommée first_name avec une longueur max de 32 caractères ( Create a column called first_name with a max-length of 32 (autorise implicitement les valeurs NULL):

    $users->column("first_name", "string", array('limit' => 32));

Ce qui génère le SQL:

    `first_name` varchar(32) NULL

Exemple C: Créons une colonne nommée first_name avec une longueur max de 64 caractères, une valeur par défaut à 'mr.' et n'autorisant pas les valeurs NULL:

    $users->column("first_name", "string", array('limit' => 64, 'default' => 'mr.', 'null' => false));

Ce qui génère le SQL:

    `first_name` varchar(64) DEFAULT 'mr.' NOT NULL

Exemple D: Créons une colonne numérique nommée post_count avec une longueur max de 4 chiffres, une valeur par défaut à 0 et la valeur NULL non autorisée:

    $users->column("post_count", "integer", array('limit' => 4, 'default' => 0, 'null' => false));

Ce qui génère le SQL:

    `post_count` integer(4) DEFAULT 0 NOT NULL

Exemple E: Créons une colonne datetime nommée created_at et la valeur NULL non autorisée:

    $users->column("created_at", "datetime", array('null' => false));

Ce qui génère le SQL:

    `created_at` datetime NOT NULL

Exemple F: Précisez votre propre clé clé primaire. Par défaut le framework va générer une colonne 'id' comme clé primaire, mais si vous voulez spécifier votre propre colonne clé primaire passez un booléen à true dans les options avec l'index 'primary_key'. Cela exige que vous spécifiez, à son tour 'id' => false dans les options de create_table.

    $t = $this->create_table('users', array('id' => false, 'options' => 'Engine=InnoDB'));
    $t->column('guid', 'string', array('primary_key' => true));
    $t->finish();

Clone this wiki locally