Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 149 lines (107 sloc) 3.832 kB
e2b6c35 @uu1101 Add short description to README.
authored
1 # plain-migrate
2c763d2 @uu1101 Add a readme.
authored
2
e2b6c35 @uu1101 Add short description to README.
authored
3 Plain migrate helps you organizing, applying and reverting changes to your
4 database schema. Its main distinctive is it being DSL-free: you can use plain
5 SQL for your migrations, and fall back to Javascript when needed.
2c763d2 @uu1101 Add a readme.
authored
6
7 # Setup
8
9 1. Create a directory to archive migrations:
10
11 ~~~~
12 $ mkdir migrations
13 ~~~~
14
15 2. Set up `config.js`:
16
17 ~~~~
18 $ cat >>config.js <<END
19 module.exports.migrations = {
20 database_url: "postgres://<username>@localhost:5432/<database_name>"
21 }
22 END
23 ~~~~
24
25 3. Create a table for recording applied migrations:
26
27 ~~~~
28 $ psql -U <username> <database_name> <<END
29 CREATE TABLE schema_migrations (
30 id numeric PRIMARY KEY
31 );
32 END
33 ~~~~
34
35 # Usage
36
37 The command line client is straightforward to use:
38
39 ~~~
40 $ plain-migrate
41 Usage: plain-migrate COMMAND
42 Where COMMAND is one of:
43 create <description> Create a new migration.
44 upgrade Run every pending migration.
45 downgrade Revert last applied migration.
46 ~~~
47
48 ## Create a migration
49
50 The first step is to initialize the directory that will contain the migration
51 scripts:
52
53 ~~~
54 $ plain-migrate create add users table
55 Created /home/user/project/migrations/1326987725537-add-users-table
56 Created /home/user/project/migrations/1326987725537-add-users-table/up.sql
57 Created /home/user/project/migrations/1326987725537-add-users-table/down.sql
58 ~~~
59
60 Then edit the upgrade script `./migrations/1326987725537-add-users-table/up.sql`:
61
62 ~~~.sql
63 CREATE TABLE users (
64 id serial PRIMARY KEY,
65 name text NOT NULL
66 );
67 ~~~
68
69 and downgrade script `./migrations/1326987725537-add-users-table/down.sql`:
70
71 ~~~.sql
72 DROP TABLE users;
73 ~~~
74
75 ## Upgrade your database
76
77 Apply this and every other pending migrations:
78
79 ~~~
80 $ plain-migrate upgrade
81 Upgrading to 1326987725537
82 ~~~
83
84 ## Downgrade your database
85
86 To revert the changes just made run:
87
88 ~~~
89 $ plain-migrate downgrade
90 Reverting 1326987725537
91 ~~~
92
93 # Configuration file
94
95 `plain-migrate` will try to obtain its configuration from a file named
96 `config.js` in the directory its called from. The configuration values should
97 be exported in a property named `migrations`. Internally, we roughly do:
98
99 ~~~.javascript
100 var config = require('./config').migrations
101 ~~~
102
103 If `plain-migrate` can't find a `config.js` file it will use the following
104 default values:
105
106 ~~~.javascript
107 var default_config = {
108 database_url: process.env.DATABASE_URL,
109 migrations_table: 'schema_migrations',
110 migrations_directory: 'migrations'
111 }
112 ~~~
113
114 `plain-migrate` will connect to the database using the url specified in
115 `DATABASE_URL` environment variable.
116
117 # Migration directory structure
118
119 Each migration is a directory. This directory can contain files named `up.sql`,
120 `down.sql` and `index.js`.
121
122 To be able to upgrade you must have the `up.sql` file or export an
123 `upgrade(callback)` method from `index.js`.
124
125 To be able to downgrade you must have the `down.sql` file or export an
126 `downgrade(callback)` method from `index.js`.
127
128 # Javascript migrations
129
130 You can use Javascript if your migration needs functionality not available in
131 SQL.
132
133 To do so you must create a file named `index.js` in the migration directory.
134 This file should export `upgrade(callback)` and `downgrade(callback)`
135 functions. As noted earlier you can omit any of them.
136
137 `this` binds to the migration object when `plain-migrate` calls those
138 functions, so it's easy to run accompanying SQL scripts `up.sql` and
139 `down.sql`, just call `this.upgrade_sql(callback)` and
140 `this.downgrade_sql(callback)`); and querying the database,
141 `this.execute(sql_string, [values], callback)` (see `pg` package's
142 documentation for further information).
143
e2b6c35 @uu1101 Add short description to README.
authored
144 # Attention: PostgreSQL only
145
146 `plain-migrate` only works with PostgreSQL and depends on the `pg` package.
147 Please, fill an issue if you need support for other databases.
148
Something went wrong with that request. Please try again.