diff options
Diffstat (limited to 'README.rst')
-rw-r--r-- | README.rst | 59 |
1 files changed, 59 insertions, 0 deletions
diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..0609d7e --- /dev/null +++ b/README.rst @@ -0,0 +1,59 @@ +Alembic is a semi-experimental database migrations tool. A migrations tool +offers the following functionality: + +* Can emit ALTER statements to a database in order to change + the structure of tables and other constructs +* Provides a system whereby "migration scripts" may be constructed; + each script indicates a particular series of steps that can "upgrade" a + target database to a new version, and optionally a series of steps that can + "downgrade" similarly, doing the same steps in reverse. +* Allows the scripts to execute in some sequential manner. + +The goals of Alembic are: + +* Very open ended and transparent configuration and operation. A new + Alembic environment is generated from a set of templates which is selected + among a set of options when setup first occurs. The templates then deposit a + series of scripts that define fully how database connectivity is established + and how migration scripts are invoked; the migration scripts themselves are + generated from a template within that series of scripts. The scripts can + then be further customized to define exactly how databases will be + interacted with and what structure new migration files should take. +* Full support for transactional DDL. The default scripts ensure that all + migrations occur within a transaction - for those databases which support + this (Postgresql, Microsoft SQL Server), migrations can be tested with no + need to manually undo changes upon failure. +* Minimalist script construction. Basic operations like renaming + tables/columns, adding/removing columns, changing column attributes can be + performed through one line commands like alter_column(), rename_table(), + add_constraint(). There is no need to recreate full SQLAlchemy Table + structures for simple operations like these - the functions themselves + generate minimalist schema structures behind the scenes to achieve the given + DDL sequence. +* Full support for migrations generated as SQL scripts. Those of us who + work in corporate environments know that direct access to DDL commands on a + production database is a rare privilege, and DBAs want textual SQL scripts. + Alembic's usage model and commands are oriented towards being able to run a + series of migrations into a textual output file as easily as it runs them + directly to a database. Care must be taken in this mode to not invoke other + operations that rely upon in-memory SELECTs of rows - Alembic tries to + provide helper constructs like bulk_insert() to help with data-oriented + operations that are compatible with script-based DDL. +* Non-linear versioning. Scripts are given UUID identifiers similarly + to a DVCS, and the linkage of one script to the next is achieved via markers + within the scripts themselves. Through this open-ended mechanism, branches + containing other migration scripts can be merged - the linkages can be + manually edited within the script files to create the new sequence. +* Provide a library of ALTER constructs that can be used by any SQLAlchemy + application. The DDL constructs build upon SQLAlchemy's own DDLElement base + and can be used standalone by any application or script. +* Don't break our necks over SQLite's inability to ALTER things. If you're + using SQLite, you really should build a system of dumping your data and + importing it back, as this backend simply does not support the migrations + use case. Alembic has no issue talking to SQLite of course but most ALTER + statements won't work. + +Alembic is working at a rudimentary level and includes a little bit of support +for Postgresql and Microsoft SQL Server. As of yet the documentation hasn't +been written - this is really the only thing left before an early release can +be put out. |