|
1 DoctrineMigrationsBundle |
|
2 ======================== |
|
3 |
|
4 The database migrations feature is an extension of the database abstraction |
|
5 layer and offers you the ability to programmatically deploy new versions of |
|
6 your database schema in a safe, easy and standardized way. |
|
7 |
|
8 .. tip:: |
|
9 |
|
10 You can read more about the Doctrine Database Migrations on the project's |
|
11 `documentation`_. |
|
12 |
|
13 Installation |
|
14 ------------ |
|
15 |
|
16 Doctrine migrations for Symfony are maintained in the `DoctrineMigrationsBundle`_. |
|
17 Make sure you have both the ``doctrine-migrations`` and ``DoctrineMigrationsBundle`` |
|
18 libraries configured in your project. Follow these steps to install the |
|
19 libraries in the Symfony Standard distribution. |
|
20 |
|
21 Add the following to ``deps``. This will register the Migrations Bundle |
|
22 and the doctrine-migrations library as dependencies in your application: |
|
23 |
|
24 .. code-block:: text |
|
25 |
|
26 [doctrine-migrations] |
|
27 git=http://github.com/doctrine/migrations.git |
|
28 |
|
29 [DoctrineMigrationsBundle] |
|
30 git=http://github.com/symfony/DoctrineMigrationsBundle.git |
|
31 target=/bundles/Symfony/Bundle/DoctrineMigrationsBundle |
|
32 |
|
33 Update the vendor libraries: |
|
34 |
|
35 .. code-block:: bash |
|
36 |
|
37 $ php bin/vendors install |
|
38 |
|
39 Next, ensure the new ``Doctrine\DBAL\Migrations`` namespace will be autoloaded |
|
40 via ``autoload.php``. The new ``Migrations`` namespace *must* be placed above |
|
41 the ``Doctrine\\DBAL`` entry so that the autoloader looks inside the migrations |
|
42 directory for those classes: |
|
43 |
|
44 .. code-block:: php |
|
45 |
|
46 // app/autoload.php |
|
47 $loader->registerNamespaces(array( |
|
48 //... |
|
49 'Doctrine\\DBAL\\Migrations' => __DIR__.'/../vendor/doctrine-migrations/lib', |
|
50 'Doctrine\\DBAL' => __DIR__.'/../vendor/doctrine-dbal/lib', |
|
51 )); |
|
52 |
|
53 Finally, be sure to enable the bundle in ``AppKernel.php`` by including the |
|
54 following: |
|
55 |
|
56 .. code-block:: php |
|
57 |
|
58 // app/AppKernel.php |
|
59 public function registerBundles() |
|
60 { |
|
61 $bundles = array( |
|
62 //... |
|
63 new Symfony\Bundle\DoctrineMigrationsBundle\DoctrineMigrationsBundle(), |
|
64 ); |
|
65 } |
|
66 |
|
67 Usage |
|
68 ----- |
|
69 |
|
70 All of the migrations functionality is contained in a few console commands: |
|
71 |
|
72 .. code-block:: bash |
|
73 |
|
74 doctrine:migrations |
|
75 :diff Generate a migration by comparing your current database to your mapping information. |
|
76 :execute Execute a single migration version up or down manually. |
|
77 :generate Generate a blank migration class. |
|
78 :migrate Execute a migration to a specified version or the latest available version. |
|
79 :status View the status of a set of migrations. |
|
80 :version Manually add and delete migration versions from the version table. |
|
81 |
|
82 Start by getting the status of migrations in your application by running |
|
83 the ``status`` command: |
|
84 |
|
85 .. code-block:: bash |
|
86 |
|
87 php app/console doctrine:migrations:status |
|
88 |
|
89 == Configuration |
|
90 |
|
91 >> Name: Application Migrations |
|
92 >> Configuration Source: manually configured |
|
93 >> Version Table Name: migration_versions |
|
94 >> Migrations Namespace: Application\Migrations |
|
95 >> Migrations Directory: /path/to/project/app/DoctrineMigrations |
|
96 >> Current Version: 0 |
|
97 >> Latest Version: 0 |
|
98 >> Executed Migrations: 0 |
|
99 >> Available Migrations: 0 |
|
100 >> New Migrations: 0 |
|
101 |
|
102 Now, you can start working with migrations by generating a new blank migration |
|
103 class. Later, you'll learn how Doctrine can generate migrations automatically |
|
104 for you. |
|
105 |
|
106 .. code-block:: bash |
|
107 |
|
108 php app/console doctrine:migrations:generate |
|
109 Generated new migration class to "/path/to/project/app/DoctrineMigrations/Version20100621140655.php" |
|
110 |
|
111 Have a look at the newly generated migration class and you will see something |
|
112 like the following:: |
|
113 |
|
114 namespace Application\Migrations; |
|
115 |
|
116 use Doctrine\DBAL\Migrations\AbstractMigration, |
|
117 Doctrine\DBAL\Schema\Schema; |
|
118 |
|
119 class Version20100621140655 extends AbstractMigration |
|
120 { |
|
121 public function up(Schema $schema) |
|
122 { |
|
123 |
|
124 } |
|
125 |
|
126 public function down(Schema $schema) |
|
127 { |
|
128 |
|
129 } |
|
130 } |
|
131 |
|
132 If you run the ``status`` command it will now show that you have one new |
|
133 migration to execute: |
|
134 |
|
135 .. code-block:: bash |
|
136 |
|
137 php app/console doctrine:migrations:status |
|
138 |
|
139 == Configuration |
|
140 |
|
141 >> Name: Application Migrations |
|
142 >> Configuration Source: manually configured |
|
143 >> Version Table Name: migration_versions |
|
144 >> Migrations Namespace: Application\Migrations |
|
145 >> Migrations Directory: /path/to/project/app/DoctrineMigrations |
|
146 >> Current Version: 0 |
|
147 >> Latest Version: 2010-06-21 14:06:55 (20100621140655) |
|
148 >> Executed Migrations: 0 |
|
149 >> Available Migrations: 1 |
|
150 >> New Migrations: 1 |
|
151 |
|
152 == Migration Versions |
|
153 |
|
154 >> 2010-06-21 14:06:55 (20100621140655) not migrated |
|
155 |
|
156 Now you can add some migration code to the ``up()`` and ``down()`` methods and |
|
157 finally migrate when you're ready: |
|
158 |
|
159 .. code-block:: bash |
|
160 |
|
161 php app/console doctrine:migrations:migrate |
|
162 |
|
163 For more information on how to write the migrations themselves (i.e. how to |
|
164 fill in the ``up()`` and ``down()`` methods), see the official Doctrine Migrations |
|
165 `documentation`_. |
|
166 |
|
167 Running Migrations during Deployment |
|
168 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
169 |
|
170 Of course, the end goal of writing migrations is to be able to use them to |
|
171 reliably update your database structure when you deploy your application. |
|
172 By running the migrations locally (or on a beta server), you can ensure that |
|
173 the migrations work as you expect. |
|
174 |
|
175 When you do finally deploy your application, you just need to remember to run |
|
176 the ``doctrine:migrations:migrate`` command. Internally, Doctrine creates |
|
177 a ``migration_versions`` table inside your database and tracks which migrations |
|
178 have been executed there. So, no matter how many migrations you've created |
|
179 and executed locally, when you run the command during deployment, Doctrine |
|
180 will know exactly which migrations it hasn't run yet by looking at the ``migration_versions`` |
|
181 table of your production database. Regardless of what server you're on, you |
|
182 can always safely run this command to execute only the migrations that haven't |
|
183 been run yet on *that* particular database. |
|
184 |
|
185 Generating Migrations Automatically |
|
186 ----------------------------------- |
|
187 |
|
188 In reality, you should rarely need to write migrations manually, as the migrations |
|
189 library can generate migration classes automatically by comparing your Doctrine |
|
190 mapping information (i.e. what your database *should* look like) with your |
|
191 actual current database structure. |
|
192 |
|
193 For example, suppose you create a new ``User`` entity and add mapping information |
|
194 for Doctrine's ORM: |
|
195 |
|
196 .. configuration-block:: |
|
197 |
|
198 .. code-block:: php-annotations |
|
199 |
|
200 // src/Acme/HelloBundle/Entity/User.php |
|
201 namespace Acme\HelloBundle\Entity; |
|
202 |
|
203 use Doctrine\ORM\Mapping as ORM; |
|
204 |
|
205 /** |
|
206 * @ORM\Entity |
|
207 * @ORM\Table(name="hello_user") |
|
208 */ |
|
209 class User |
|
210 { |
|
211 /** |
|
212 * @ORM\Id |
|
213 * @ORM\Column(type="integer") |
|
214 * @ORM\GeneratedValue(strategy="AUTO") |
|
215 */ |
|
216 protected $id; |
|
217 |
|
218 /** |
|
219 * @ORM\Column(type="string", length="255") |
|
220 */ |
|
221 protected $name; |
|
222 } |
|
223 |
|
224 .. code-block:: yaml |
|
225 |
|
226 # src/Acme/HelloBundle/Resources/config/doctrine/User.orm.yml |
|
227 Acme\HelloBundle\Entity\User: |
|
228 type: entity |
|
229 table: hello_user |
|
230 id: |
|
231 id: |
|
232 type: integer |
|
233 generator: |
|
234 strategy: AUTO |
|
235 fields: |
|
236 name: |
|
237 type: string |
|
238 length: 255 |
|
239 |
|
240 .. code-block:: xml |
|
241 |
|
242 <!-- src/Acme/HelloBundle/Resources/config/doctrine/User.orm.xml --> |
|
243 <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping" |
|
244 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
|
245 xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping |
|
246 http://doctrine-project.org/schemas/orm/doctrine-mapping.xsd"> |
|
247 |
|
248 <entity name="Acme\HelloBundle\Entity\User" table="hello_user"> |
|
249 <id name="id" type="integer" column="id"> |
|
250 <generator strategy="AUTO"/> |
|
251 </id> |
|
252 <field name="name" column="name" type="string" length="255" /> |
|
253 </entity> |
|
254 |
|
255 </doctrine-mapping> |
|
256 |
|
257 With this information, Doctrine is now ready to help you persist your new |
|
258 ``User`` object to and from the ``hello_user`` table. Of course, this table |
|
259 doesn't exist yet! Generate a new migration for this table automatically by |
|
260 running the following command: |
|
261 |
|
262 .. code-block:: bash |
|
263 |
|
264 php app/console doctrine:migrations:diff |
|
265 |
|
266 You should see a message that a new migration class was generated based on |
|
267 the schema differences. If you open this file, you'll find that it has the |
|
268 SQL code needed to create the ``hello_user`` table. Next, run the migration |
|
269 to add the table to your database: |
|
270 |
|
271 .. code-block:: bash |
|
272 |
|
273 php app/console doctrine:migrations:migrate |
|
274 |
|
275 The moral of the story is this: after each change you make to your Doctrine |
|
276 mapping information, run the ``doctrine:migrations:diff`` command to automatically |
|
277 generate your migration classes. |
|
278 |
|
279 If you do this from the very beginning of your project (i.e. so that even |
|
280 the first tables were loaded via a migration class), you'll always be able |
|
281 to create a fresh database and run your migrations in order to get your database |
|
282 schema fully up to date. In fact, this is an easy and dependable workflow |
|
283 for your project. |
|
284 |
|
285 .. _documentation: http://www.doctrine-project.org/projects/migrations/2.0/docs/reference/introduction/en |
|
286 .. _DoctrineMigrationsBundle: https://github.com/symfony/DoctrineMigrationsBundle |