Show More
api.py
386 lines
| 12.9 KiB
| text/x-python
|
PythonLexer
r1 | """ | |||
This module provides an external API to the versioning system. | ||||
.. versionchanged:: 0.6.0 | ||||
:func:`migrate.versioning.api.test` and schema diff functions | ||||
changed order of positional arguments so all accept `url` and `repository` | ||||
as first arguments. | ||||
.. versionchanged:: 0.5.4 | ||||
``--preview_sql`` displays source file when using SQL scripts. | ||||
If Python script is used, it runs the action with mocked engine and | ||||
returns captured SQL statements. | ||||
.. versionchanged:: 0.5.4 | ||||
Deprecated ``--echo`` parameter in favour of new | ||||
:func:`migrate.versioning.util.construct_engine` behavior. | ||||
""" | ||||
# Dear migrate developers, | ||||
# | ||||
# please do not comment this module using sphinx syntax because its | ||||
# docstrings are presented as user help and most users cannot | ||||
# interpret sphinx annotated ReStructuredText. | ||||
# | ||||
# Thanks, | ||||
# Jan Dittberner | ||||
import sys | ||||
import inspect | ||||
import logging | ||||
from rhodecode.lib.dbmigrate.migrate import exceptions | ||||
from rhodecode.lib.dbmigrate.migrate.versioning import ( | ||||
repository, schema, version, | ||||
script as script_ # command name conflict | ||||
) | ||||
from rhodecode.lib.dbmigrate.migrate.versioning.util import ( | ||||
catch_known_errors, with_engine) | ||||
log = logging.getLogger(__name__) | ||||
command_desc = { | ||||
'help': 'displays help on a given command', | ||||
'create': 'create an empty repository at the specified path', | ||||
'script': 'create an empty change Python script', | ||||
'script_sql': 'create empty change SQL scripts for given database', | ||||
'version': 'display the latest version available in a repository', | ||||
'db_version': 'show the current version of the repository under version control', | ||||
'source': 'display the Python code for a particular version in this repository', | ||||
'version_control': 'mark a database as under this repository\'s version control', | ||||
'upgrade': 'upgrade a database to a later version', | ||||
'downgrade': 'downgrade a database to an earlier version', | ||||
'drop_version_control': 'removes version control from a database', | ||||
'manage': 'creates a Python script that runs Migrate with a set of default values', | ||||
'test': 'performs the upgrade and downgrade command on the given database', | ||||
'compare_model_to_db': 'compare MetaData against the current database state', | ||||
'create_model': 'dump the current database as a Python model to stdout', | ||||
'make_update_script_for_model': 'create a script changing the old MetaData to the new (current) MetaData', | ||||
'update_db_from_model': 'modify the database to match the structure of the current MetaData', | ||||
} | ||||
__all__ = command_desc.keys() | ||||
Repository = repository.Repository | ||||
ControlledSchema = schema.ControlledSchema | ||||
VerNum = version.VerNum | ||||
PythonScript = script_.PythonScript | ||||
SqlScript = script_.SqlScript | ||||
# deprecated | ||||
def help(cmd=None, **opts): | ||||
"""%prog help COMMAND | ||||
Displays help on a given command. | ||||
""" | ||||
if cmd is None: | ||||
raise exceptions.UsageError(None) | ||||
try: | ||||
func = globals()[cmd] | ||||
except: | ||||
raise exceptions.UsageError( | ||||
"'%s' isn't a valid command. Try 'help COMMAND'" % cmd) | ||||
ret = func.__doc__ | ||||
if sys.argv[0]: | ||||
ret = ret.replace('%prog', sys.argv[0]) | ||||
return ret | ||||
@catch_known_errors | ||||
def create(repository, name, **opts): | ||||
"""%prog create REPOSITORY_PATH NAME [--table=TABLE] | ||||
Create an empty repository at the specified path. | ||||
You can specify the version_table to be used; by default, it is | ||||
'migrate_version'. This table is created in all version-controlled | ||||
databases. | ||||
""" | ||||
repo_path = Repository.create(repository, name, **opts) | ||||
@catch_known_errors | ||||
def script(description, repository, **opts): | ||||
"""%prog script DESCRIPTION REPOSITORY_PATH | ||||
Create an empty change script using the next unused version number | ||||
appended with the given description. | ||||
For instance, manage.py script "Add initial tables" creates: | ||||
repository/versions/001_Add_initial_tables.py | ||||
""" | ||||
repo = Repository(repository) | ||||
repo.create_script(description, **opts) | ||||
@catch_known_errors | ||||
def script_sql(database, description, repository, **opts): | ||||
"""%prog script_sql DATABASE DESCRIPTION REPOSITORY_PATH | ||||
Create empty change SQL scripts for given DATABASE, where DATABASE | ||||
is either specific ('postgresql', 'mysql', 'oracle', 'sqlite', etc.) | ||||
or generic ('default'). | ||||
For instance, manage.py script_sql postgresql description creates: | ||||
repository/versions/001_description_postgresql_upgrade.sql and | ||||
repository/versions/001_description_postgresql_downgrade.sql | ||||
""" | ||||
repo = Repository(repository) | ||||
repo.create_script_sql(database, description, **opts) | ||||
def version(repository, **opts): | ||||
"""%prog version REPOSITORY_PATH | ||||
Display the latest version available in a repository. | ||||
""" | ||||
repo = Repository(repository) | ||||
return repo.latest | ||||
@with_engine | ||||
def db_version(url, repository, **opts): | ||||
"""%prog db_version URL REPOSITORY_PATH | ||||
Show the current version of the repository with the given | ||||
connection string, under version control of the specified | ||||
repository. | ||||
The url should be any valid SQLAlchemy connection string. | ||||
""" | ||||
engine = opts.pop('engine') | ||||
schema = ControlledSchema(engine, repository) | ||||
return schema.version | ||||
def source(version, dest=None, repository=None, **opts): | ||||
"""%prog source VERSION [DESTINATION] --repository=REPOSITORY_PATH | ||||
Display the Python code for a particular version in this | ||||
repository. Save it to the file at DESTINATION or, if omitted, | ||||
send to stdout. | ||||
""" | ||||
if repository is None: | ||||
raise exceptions.UsageError("A repository must be specified") | ||||
repo = Repository(repository) | ||||
ret = repo.version(version).script().source() | ||||
if dest is not None: | ||||
with open(dest, 'w') as f: | ||||
f.write(ret) | ||||
ret = None | ||||
return ret | ||||
def upgrade(url, repository, version=None, **opts): | ||||
"""%prog upgrade URL REPOSITORY_PATH [VERSION] [--preview_py|--preview_sql] | ||||
Upgrade a database to a later version. | ||||
This runs the upgrade() function defined in your change scripts. | ||||
By default, the database is updated to the latest available | ||||
version. You may specify a version instead, if you wish. | ||||
You may preview the Python or SQL code to be executed, rather than | ||||
actually executing it, using the appropriate 'preview' option. | ||||
""" | ||||
err = "Cannot upgrade a database of version %s to version %s. "\ | ||||
"Try 'downgrade' instead." | ||||
return _migrate(url, repository, version, upgrade=True, err=err, **opts) | ||||
def downgrade(url, repository, version, **opts): | ||||
"""%prog downgrade URL REPOSITORY_PATH VERSION [--preview_py|--preview_sql] | ||||
Downgrade a database to an earlier version. | ||||
This is the reverse of upgrade; this runs the downgrade() function | ||||
defined in your change scripts. | ||||
You may preview the Python or SQL code to be executed, rather than | ||||
actually executing it, using the appropriate 'preview' option. | ||||
""" | ||||
err = "Cannot downgrade a database of version %s to version %s. "\ | ||||
"Try 'upgrade' instead." | ||||
return _migrate(url, repository, version, upgrade=False, err=err, **opts) | ||||
@with_engine | ||||
def test(url, repository, **opts): | ||||
"""%prog test URL REPOSITORY_PATH [VERSION] | ||||
Performs the upgrade and downgrade option on the given | ||||
database. This is not a real test and may leave the database in a | ||||
bad state. You should therefore better run the test on a copy of | ||||
your database. | ||||
""" | ||||
engine = opts.pop('engine') | ||||
repos = Repository(repository) | ||||
# Upgrade | ||||
log.info("Upgrading...") | ||||
script = repos.version(None).script(engine.name, 'upgrade') | ||||
script.run(engine, 1) | ||||
log.info("done") | ||||
log.info("Downgrading...") | ||||
script = repos.version(None).script(engine.name, 'downgrade') | ||||
script.run(engine, -1) | ||||
log.info("done") | ||||
log.info("Success") | ||||
@with_engine | ||||
def version_control(url, repository, version=None, **opts): | ||||
"""%prog version_control URL REPOSITORY_PATH [VERSION] | ||||
Mark a database as under this repository's version control. | ||||
Once a database is under version control, schema changes should | ||||
only be done via change scripts in this repository. | ||||
This creates the table version_table in the database. | ||||
The url should be any valid SQLAlchemy connection string. | ||||
By default, the database begins at version 0 and is assumed to be | ||||
empty. If the database is not empty, you may specify a version at | ||||
which to begin instead. No attempt is made to verify this | ||||
version's correctness - the database schema is expected to be | ||||
identical to what it would be if the database were created from | ||||
scratch. | ||||
""" | ||||
engine = opts.pop('engine') | ||||
ControlledSchema.create(engine, repository, version) | ||||
@with_engine | ||||
def drop_version_control(url, repository, **opts): | ||||
"""%prog drop_version_control URL REPOSITORY_PATH | ||||
Removes version control from a database. | ||||
""" | ||||
engine = opts.pop('engine') | ||||
schema = ControlledSchema(engine, repository) | ||||
schema.drop() | ||||
def manage(file, **opts): | ||||
"""%prog manage FILENAME [VARIABLES...] | ||||
Creates a script that runs Migrate with a set of default values. | ||||
For example:: | ||||
%prog manage manage.py --repository=/path/to/repository \ | ||||
--url=sqlite:///project.db | ||||
would create the script manage.py. The following two commands | ||||
would then have exactly the same results:: | ||||
python manage.py version | ||||
%prog version --repository=/path/to/repository | ||||
""" | ||||
Repository.create_manage_file(file, **opts) | ||||
@with_engine | ||||
def compare_model_to_db(url, repository, model, **opts): | ||||
"""%prog compare_model_to_db URL REPOSITORY_PATH MODEL | ||||
Compare the current model (assumed to be a module level variable | ||||
of type sqlalchemy.MetaData) against the current database. | ||||
NOTE: This is EXPERIMENTAL. | ||||
""" # TODO: get rid of EXPERIMENTAL label | ||||
engine = opts.pop('engine') | ||||
return ControlledSchema.compare_model_to_db(engine, model, repository) | ||||
@with_engine | ||||
def create_model(url, repository, **opts): | ||||
"""%prog create_model URL REPOSITORY_PATH [DECLERATIVE=True] | ||||
Dump the current database as a Python model to stdout. | ||||
NOTE: This is EXPERIMENTAL. | ||||
""" # TODO: get rid of EXPERIMENTAL label | ||||
engine = opts.pop('engine') | ||||
declarative = opts.get('declarative', False) | ||||
return ControlledSchema.create_model(engine, repository, declarative) | ||||
@catch_known_errors | ||||
@with_engine | ||||
def make_update_script_for_model(url, repository, oldmodel, model, **opts): | ||||
"""%prog make_update_script_for_model URL OLDMODEL MODEL REPOSITORY_PATH | ||||
Create a script changing the old Python model to the new (current) | ||||
Python model, sending to stdout. | ||||
NOTE: This is EXPERIMENTAL. | ||||
""" # TODO: get rid of EXPERIMENTAL label | ||||
engine = opts.pop('engine') | ||||
return PythonScript.make_update_script_for_model( | ||||
engine, oldmodel, model, repository, **opts) | ||||
@with_engine | ||||
def update_db_from_model(url, repository, model, **opts): | ||||
"""%prog update_db_from_model URL REPOSITORY_PATH MODEL | ||||
Modify the database to match the structure of the current Python | ||||
model. This also sets the db_version number to the latest in the | ||||
repository. | ||||
NOTE: This is EXPERIMENTAL. | ||||
""" # TODO: get rid of EXPERIMENTAL label | ||||
engine = opts.pop('engine') | ||||
schema = ControlledSchema(engine, repository) | ||||
schema.update_db_from_model(model) | ||||
@with_engine | ||||
def _migrate(url, repository, version, upgrade, err, **opts): | ||||
engine = opts.pop('engine') | ||||
url = str(engine.url) | ||||
schema = ControlledSchema(engine, repository) | ||||
version = _migrate_version(schema, version, upgrade, err) | ||||
changeset = schema.changeset(version) | ||||
for ver, change in changeset: | ||||
nextver = ver + changeset.step | ||||
log.info('%s -> %s... ', ver, nextver) | ||||
if opts.get('preview_sql'): | ||||
if isinstance(change, PythonScript): | ||||
log.info(change.preview_sql(url, changeset.step, **opts)) | ||||
elif isinstance(change, SqlScript): | ||||
log.info(change.source()) | ||||
elif opts.get('preview_py'): | ||||
if not isinstance(change, PythonScript): | ||||
raise exceptions.UsageError("Python source can be only displayed" | ||||
" for python migration files") | ||||
source_ver = max(ver, nextver) | ||||
module = schema.repository.version(source_ver).script().module | ||||
funcname = upgrade and "upgrade" or "downgrade" | ||||
func = getattr(module, funcname) | ||||
log.info(inspect.getsource(func)) | ||||
else: | ||||
schema.runchange(ver, change, changeset.step) | ||||
log.info('done') | ||||
def _migrate_version(schema, version, upgrade, err): | ||||
if version is None: | ||||
return version | ||||
# Version is specified: ensure we're upgrading in the right direction | ||||
# (current version < target version for upgrading; reverse for down) | ||||
version = VerNum(version) | ||||
cur = schema.version | ||||
if upgrade is not None: | ||||
if upgrade: | ||||
direction = cur <= version | ||||
else: | ||||
direction = cur >= version | ||||
if not direction: | ||||
raise exceptions.KnownError(err % (cur, version)) | ||||
return version | ||||