From: Mike Bayer Date: Tue, 28 Jun 2011 17:29:23 +0000 (-0400) Subject: format to 79 char X-Git-Tag: rel_0_1_0~71 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=16e83b94f041a2dc7c306fa31a5a4d8826d777fd;p=thirdparty%2Fsqlalchemy%2Falembic.git format to 79 char --- diff --git a/README b/README index 9b97c497..0609d7e9 100644 --- a/README +++ b/README @@ -1,49 +1,59 @@ -Alembic is a semi-experimental database migrations tool. A migrations tool +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. +* 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. +* 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 +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.