diff --git a/alembic/environment.py b/alembic/environment.py index 716de62..d562add 100644 --- a/alembic/environment.py +++ b/alembic/environment.py @@ -5,7 +5,15 @@ from contextlib import contextmanager class EnvironmentContext(object): - """Represent the state made available to an env.py script.""" + """Represent the state made available to an ``env.py`` script. + + :class:`.EnvironmentContext` is normally instantiated + by the commands present in the :mod:`alembic.command` + module. From within an ``env.py`` script, the current + :class:`.EnvironmentContext` is available via the + ``alembic.context`` datamember. + + """ _migration_context = None _default_opts = None @@ -150,11 +158,20 @@ def configure(self, sqlalchemy_module_prefix="sa.", **kw ): - """Configure the migration environment. - - The important thing needed here is first a way to figure out - what kind of "dialect" is in use. The second is to pass - an actual database connection, if one is required. + """Configure a :class:`.MigrationContext` within this + :class:`.EnvironmentContext` which will provide database connectivity + and other configuration to a series of migration scripts. + + Many methods on :class:`.EnvironmentContext` require that + this method has been called in order to function, as they + ultimately need to have database access or at least access + to the dialect in use. Those which do are documented as such. + + The important thing needed by :meth:`.configure` is a + means to determine what kind of database dialect is in use. + An actual connection to that database is needed only if + the :class:`.MigrationContext` is to be used in + "online" mode. If the :meth:`.is_offline_mode` function returns ``True``, then no connection is needed here. Otherwise, the @@ -420,11 +437,6 @@ def migration_context(self): If :meth:`.EnvironmentContext.configure` has not been called yet, raises an exception. - Generally, env.py scripts should access this via - the ``alembic.context`` object, which is an instance of - :class:`.MigrationContext` placed there for the duration - of the env.py script's usage. - """ if self._migration_context is None: raise Exception("No context has been configured yet.") diff --git a/alembic/operations.py b/alembic/operations.py index 7d59c41..18b8e69 100644 --- a/alembic/operations.py +++ b/alembic/operations.py @@ -13,9 +13,23 @@ class Operations(object): Each operation corresponds to some schema migration operation, executed against a particular :class:`.MigrationContext`. + Normally, the :class:`.MigrationContext` is created + within an ``env.py`` script via the + :meth:`.EnvironmentContext.configure` method. However, + the :class:`.Operations` object can also be used without + actually using the :class:`.EnvironmentContext` + class - only :class:`.MigrationContext`, which represents + connectivity to a single database, is needed + to use the directives. + """ def __init__(self, migration_context): - """Construct a new :class:`.Operations`""" + """Construct a new :class:`.Operations` + + :param migration_context: a :class:`.MigrationContext` + instance. + + """ self.migration_context = migration_context self.impl = migration_context.impl diff --git a/docs/build/api.rst b/docs/build/api.rst index 8541cbf..3abc955 100644 --- a/docs/build/api.rst +++ b/docs/build/api.rst @@ -5,18 +5,51 @@ API Details This section describes some key functions used within the migration process, particularly those referenced within a migration environment's ``env.py`` file. +Overview +======== + +The three main objects in use are the :class:`.EnvironmentContext`, :class:`.MigrationContext`, +and :class:`.Operations` classes, pictured below. + +.. image:: api_overview.png + +An Alembic command begins by instantiating an :class:`.EnvironmentContext` object, then +making it available via the ``alembic.context`` datamember. The ``env.py`` +script, representing a user-configurable migration environment, is then +invoked. The ``env.py`` script is then responsible for calling upon the +:meth:`.EnvironmentContext.configure`, whose job it is to create +a :class:`.MigrationContext` object. + +Before this method is called, there's not +yet any database connection or dialect-specific state set up. While +many methods on :class:`.EnvironmentContext` are usable at this stage, +those which require database access, or at least access to the kind +of database dialect in use, are not. Once the +:meth:`.EnvironmentContext.configure` method is called, the :class:`.EnvironmentContext` +is said to be *configured* with database connectivity, available via +a new :class:`.MigrationContext` object. The :class:`.MigrationContext` +is associated with the :class:`.EnvironmentContext` object +via the :attr:`.EnvironmentContext.migration_context` datamember. + +Finally, ``env.py`` calls upon the :meth:`.EnvironmentContext.run_migrations` +method. Within this method, a new :class:`.Operations` object, which +provides an API for individual database migration operations, is established +within the ``alembic.op`` datamember. The :class:`.Operations` object +uses the :class:`.MigrationContext` object ultimately as a source of +database connectivity, though in such a way that it does not care if the +:class:`.MigrationContext` is talking to a real database or just writing +out SQL to a file. + env.py Directives ================= -The :mod:`alembic.environment` module contains API features that are generally used within -``env.py`` files. +This section covers the objects that are generally used within an +``env.py`` environmental configuration script. Alembic normally generates +this script for you; it is however made available locally within the migrations +environment so that it can be customized. -The central object in use is the :class:`.EnvironmentContext` object. This object is -made present when the ``env.py`` script calls upon the :meth:`.EnvironmentContext.configure` -method for the first time. Before this function is called, there's not -yet any database connection or dialect-specific state set up, and those -functions which require this state will raise an exception when used, -until :meth:`.EnvironmentContext.configure` is called successfully. +In particular, the key method used within ``env.py`` is :meth:`.EnvironmentContext.configure`, +which establishes all the details about how the database will be accessed. .. autofunction:: sqlalchemy.engine.engine_from_config @@ -27,7 +60,6 @@ until :meth:`.EnvironmentContext.configure` is called successfully. .. automodule:: alembic.migration :members: - Commands ========= diff --git a/docs/build/api_overview.png b/docs/build/api_overview.png new file mode 100644 index 0000000..1ad7993 Binary files /dev/null and b/docs/build/api_overview.png differ diff --git a/docs/build/assets/api_overview.graffle b/docs/build/assets/api_overview.graffle new file mode 100644 index 0000000..b363d52 --- /dev/null +++ b/docs/build/assets/api_overview.graffle @@ -0,0 +1,1181 @@ + + + + + ActiveLayerIndex + 0 + AutoAdjust + + CanvasColor + + w + 1 + + CanvasOrigin + {0, 0} + CanvasScale + 1 + ColumnAlign + 1 + ColumnSpacing + 36 + CreationDate + 2012-01-24 16:51:07 -0500 + Creator + classic + DisplayScale + 1 in = 1 in + GraphDocumentVersion + 5 + GraphicsList + + + Class + LineGraphic + Head + + ID + 2048 + + ID + 2051 + Points + + {165, 221.6} + {109, 221.6} + + Style + + stroke + + HeadArrow + StickArrow + Pattern + 1 + TailArrow + 0 + + + Tail + + ID + 33 + + + + Class + TableGroup + Graphics + + + Bounds + {{19, 207.6}, {90, 14}} + Class + ShapedGraphic + FitText + Vertical + Flow + Resize + ID + 2049 + Shape + Rectangle + Style + + fill + + GradientAngle + 304 + GradientCenter + {-0.294118, -0.264706} + + + Text + + Text + {\rtf1\ansi\ansicpg1252\cocoartf1038\cocoasubrtf360 +{\fonttbl\f0\fswiss\fcharset0 Helvetica;} +{\colortbl;\red255\green255\blue255;} +\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\qc + +\f0\b\fs24 \cf0 Config} + + TextPlacement + 0 + + + Bounds + {{19, 221.6}, {90, 14}} + Class + ShapedGraphic + FitText + Vertical + Flow + Resize + ID + 2050 + Shape + Rectangle + Style + + fill + + GradientAngle + 304 + GradientCenter + {-0.294118, -0.264706} + + + Text + + Align + 0 + Text + {\rtf1\ansi\ansicpg1252\cocoartf1038\cocoasubrtf360 +{\fonttbl\f0\fswiss\fcharset0 Helvetica;} +{\colortbl;\red255\green255\blue255;} +\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural + +\f0\fs24 \cf0 ConfigParser} + + TextPlacement + 0 + + + GridH + + 2049 + 2050 + + + GroupConnect + YES + ID + 2048 + + + Class + LineGraphic + Head + + ID + 2042 + + ID + 2046 + OrthogonalBarAutomatic + + OrthogonalBarPosition + 28.725006103515625 + Points + + {304, 198.756} + {385.25, 157} + + Style + + stroke + + HeadArrow + StickArrow + LineType + 2 + Pattern + 1 + TailArrow + 0 + + + Tail + + ID + 33 + + + + Class + LineGraphic + Head + + ID + 2043 + + ID + 2044 + OrthogonalBarAutomatic + + OrthogonalBarPosition + 52.850021362304688 + Points + + {433.496, 294.6} + {454.25, 177} + + Style + + stroke + + HeadArrow + StickArrow + LineType + 2 + Pattern + 1 + TailArrow + 0 + + + Tail + + ID + 38 + + + + Bounds + {{385.25, 172}, {69, 14}} + Class + ShapedGraphic + FitText + YES + Flow + Resize + ID + 2043 + Magnets + + {0.5, -0.142857} + + Shape + Rectangle + Style + + fill + + Draws + NO + + shadow + + Draws + NO + + stroke + + Draws + NO + + + Text + + Text + {\rtf1\ansi\ansicpg1252\cocoartf1038\cocoasubrtf360 +{\fonttbl\f0\fswiss\fcharset0 Helvetica;} +{\colortbl;\red255\green255\blue255;} +\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\qc\pardirnatural + +\f0\fs24 \cf0 alembic.op} + + Wrap + NO + + + Bounds + {{385.25, 149.6}, {94, 14}} + Class + ShapedGraphic + FitText + YES + Flow + Resize + ID + 2042 + Magnets + + {0.49734, 0.0285711} + + Shape + Rectangle + Style + + fill + + Draws + NO + + shadow + + Draws + NO + + stroke + + Draws + NO + + + Text + + Text + {\rtf1\ansi\ansicpg1252\cocoartf1038\cocoasubrtf360 +{\fonttbl\f0\fswiss\fcharset0 Helvetica;} +{\colortbl;\red255\green255\blue255;} +\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\qc\pardirnatural + +\f0\fs24 \cf0 alembic.context} + + Wrap + NO + + + Class + LineGraphic + Head + + ID + 2038 + + ID + 2040 + Points + + {166.088, 336.6} + {105.686, 336.6} + + Style + + stroke + + HeadArrow + StickArrow + Pattern + 1 + TailArrow + 0 + + + Tail + + ID + 41 + + + + Bounds + {{19, 294.6}, {86.1858, 84}} + Class + ShapedGraphic + ID + 2038 + Shape + Cylinder + Text + + Text + {\rtf1\ansi\ansicpg1252\cocoartf1038\cocoasubrtf360 +{\fonttbl\f0\fswiss\fcharset0 Helvetica;} +{\colortbl;\red255\green255\blue255;} +\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\qc\pardirnatural + +\f0\fs24 \cf0 database} + + + + Bounds + {{227.597, 278.569}, {55, 12}} + Class + ShapedGraphic + FitText + YES + ID + 51 + Line + + ID + 50 + Offset + -20 + Position + 0.40689659118652344 + RotationType + 0 + + Shape + Rectangle + Style + + shadow + + Draws + NO + + stroke + + Draws + NO + + + Text + + Align + 0 + Text + {\rtf1\ansi\ansicpg1252\cocoartf1038\cocoasubrtf360 +{\fonttbl\f0\fswiss\fcharset0 Helvetica;} +{\colortbl;\red255\green255\blue255;} +\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural + +\f0\fs20 \cf0 <<uses>>} + + + + Class + LineGraphic + Head + + ID + 41 + + ID + 50 + Points + + {234.897, 263.6} + {235.389, 315.6} + + Style + + stroke + + HeadArrow + StickArrow + Pattern + 1 + TailArrow + 0 + + + Tail + + ID + 33 + + + + Bounds + {{308.265, 310.6}, {55, 12}} + Class + ShapedGraphic + FitText + YES + ID + 49 + Line + + ID + 9 + Offset + -20 + Position + 0.5199354887008667 + RotationType + 0 + + Shape + Rectangle + Style + + shadow + + Draws + NO + + stroke + + Draws + NO + + + Text + + Align + 0 + Text + {\rtf1\ansi\ansicpg1252\cocoartf1038\cocoasubrtf360 +{\fonttbl\f0\fswiss\fcharset0 Helvetica;} +{\colortbl;\red255\green255\blue255;} +\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural + +\f0\fs20 \cf0 <<uses>>} + + + + Class + LineGraphic + Head + + ID + 41 + + ID + 9 + Points + + {368.99, 336.6} + {305.088, 336.6} + + Style + + stroke + + HeadArrow + StickArrow + Pattern + 1 + TailArrow + 0 + + + Tail + + ID + 38 + + + + Class + TableGroup + Graphics + + + Bounds + {{166.088, 315.6}, {139, 14}} + Class + ShapedGraphic + FitText + Vertical + Flow + Resize + ID + 42 + Shape + Rectangle + Style + + fill + + GradientAngle + 304 + GradientCenter + {-0.294118, -0.264706} + + + Text + + Text + {\rtf1\ansi\ansicpg1252\cocoartf1038\cocoasubrtf360 +{\fonttbl\f0\fswiss\fcharset0 Helvetica;} +{\colortbl;\red255\green255\blue255;} +\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\qc + +\f0\b\fs24 \cf0 MigrationContext} + + TextPlacement + 0 + + + Bounds + {{166.088, 329.6}, {139, 28}} + Class + ShapedGraphic + FitText + Vertical + Flow + Resize + ID + 44 + Shape + Rectangle + Style + + fill + + GradientAngle + 304 + GradientCenter + {-0.294118, -0.264706} + + + Text + + Align + 0 + Text + {\rtf1\ansi\ansicpg1252\cocoartf1038\cocoasubrtf360 +{\fonttbl\f0\fswiss\fcharset0 Helvetica;} +{\colortbl;\red255\green255\blue255;} +\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural\pardirnatural + +\f0\fs24 \cf0 connection\ +run_migrations()} + + TextPlacement + 0 + + + GridH + + 42 + 44 + + + GroupConnect + YES + ID + 41 + + + Class + TableGroup + Graphics + + + Bounds + {{368.99, 294.6}, {139, 14}} + Class + ShapedGraphic + FitText + Vertical + Flow + Resize + ID + 39 + Shape + Rectangle + Style + + fill + + GradientAngle + 304 + GradientCenter + {-0.294118, -0.264706} + + + Text + + Text + {\rtf1\ansi\ansicpg1252\cocoartf1038\cocoasubrtf360 +{\fonttbl\f0\fswiss\fcharset0 Helvetica;} +{\colortbl;\red255\green255\blue255;} +\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\qc + +\f0\b\fs24 \cf0 Operations} + + TextPlacement + 0 + + + Bounds + {{368.99, 308.6}, {139, 70}} + Class + ShapedGraphic + FitText + Vertical + Flow + Resize + ID + 40 + Shape + Rectangle + Style + + fill + + GradientAngle + 304 + GradientCenter + {-0.294118, -0.264706} + + + Text + + Align + 0 + Text + {\rtf1\ansi\ansicpg1252\cocoartf1038\cocoasubrtf360 +{\fonttbl\f0\fswiss\fcharset0 Helvetica;} +{\colortbl;\red255\green255\blue255;} +\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural + +\f0\fs24 \cf0 migration_context\ +create_table()\ +alter_column()\ +add_column()\ +drop_column()} + + TextPlacement + 0 + + + GridH + + 39 + 40 + + + GroupConnect + YES + ID + 38 + + + Class + TableGroup + Graphics + + + Bounds + {{165, 179.6}, {139, 14}} + Class + ShapedGraphic + FitText + Vertical + Flow + Resize + ID + 34 + Shape + Rectangle + Style + + fill + + GradientAngle + 304 + GradientCenter + {-0.294118, -0.264706} + + + Text + + Text + {\rtf1\ansi\ansicpg1252\cocoartf1038\cocoasubrtf360 +{\fonttbl\f0\fswiss\fcharset0 Helvetica;} +{\colortbl;\red255\green255\blue255;} +\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\qc + +\f0\b\fs24 \cf0 EnvironmentContext} + + TextPlacement + 0 + + + Bounds + {{165, 193.6}, {139, 70}} + Class + ShapedGraphic + FitText + Vertical + Flow + Resize + ID + 35 + Shape + Rectangle + Style + + fill + + GradientAngle + 304 + GradientCenter + {-0.294118, -0.264706} + + + Text + + Align + 0 + Text + {\rtf1\ansi\ansicpg1252\cocoartf1038\cocoasubrtf360 +{\fonttbl\f0\fswiss\fcharset0 Helvetica;} +{\colortbl;\red255\green255\blue255;} +\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural + +\f0\fs24 \cf0 migration_context\ +configure()\ +run_migrations()\ +begin_transaction()\ +is_offline_mode()} + + TextPlacement + 0 + + + GridH + + 34 + 35 + + + GroupConnect + YES + ID + 33 + + + Bounds + {{153.176, 149.6}, {164.824, 255}} + Class + ShapedGraphic + ID + 2036 + Shape + Rectangle + Style + + fill + + Draws + NO + + shadow + + Draws + NO + Fuzziness + 0.0 + + stroke + + Color + + b + 0.191506 + g + 0.389204 + r + 0.744565 + + CornerRadius + 5 + Pattern + 1 + + + Text + + Align + 0 + Text + {\rtf1\ansi\ansicpg1252\cocoartf1038\cocoasubrtf360 +{\fonttbl\f0\fswiss\fcharset0 Helvetica;} +{\colortbl;\red255\green255\blue255;} +\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural\pardirnatural + +\f0\fs24 \cf0 env.py script} + + TextPlacement + 0 + Wrap + NO + + + Bounds + {{343.99, 259.266}, {189, 145.334}} + Class + ShapedGraphic + ID + 2032 + Shape + Rectangle + Style + + fill + + Draws + NO + + shadow + + Draws + NO + Fuzziness + 0.0 + + stroke + + Color + + b + 0.191506 + g + 0.389204 + r + 0.744565 + + CornerRadius + 5 + Pattern + 1 + + + Text + + Align + 0 + Text + {\rtf1\ansi\ansicpg1252\cocoartf1038\cocoasubrtf360 +{\fonttbl\f0\fswiss\fcharset0 Helvetica;} +{\colortbl;\red255\green255\blue255;} +\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural\pardirnatural + +\f0\fs24 \cf0 migration script} + + TextPlacement + 0 + Wrap + NO + + + Bounds + {{138.176, 127.6}, {420.824, 293.4}} + Class + ShapedGraphic + ID + 2037 + Shape + Rectangle + Style + + fill + + Draws + NO + + shadow + + Draws + NO + Fuzziness + 0.0 + + stroke + + Color + + b + 0.191506 + g + 0.389204 + r + 0.744565 + + CornerRadius + 5 + Pattern + 1 + + + Text + + Align + 0 + Text + {\rtf1\ansi\ansicpg1252\cocoartf1038\cocoasubrtf360 +{\fonttbl\f0\fswiss\fcharset0 Helvetica;} +{\colortbl;\red255\green255\blue255;} +\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural\pardirnatural + +\f0\fs24 \cf0 alembic command} + + TextPlacement + 0 + Wrap + NO + + + GridInfo + + GuidesLocked + NO + GuidesVisible + YES + HPages + 1 + ImageCounter + 1 + IsPalette + NO + KeepToScale + + Layers + + + Lock + NO + Name + Layer 1 + Print + YES + View + YES + + + LayoutInfo + + LinksVisible + NO + MagnetsVisible + NO + MasterSheet + Master 1 + MasterSheets + + + ActiveLayerIndex + 0 + AutoAdjust + + CanvasColor + + w + 1 + + CanvasOrigin + {0, 0} + CanvasScale + 1 + ColumnAlign + 1 + ColumnSpacing + 36 + DisplayScale + 1 in = 1 in + GraphicsList + + GridInfo + + HPages + 1 + IsPalette + NO + KeepToScale + + Layers + + + Lock + NO + Name + Layer 1 + Print + YES + View + YES + + + LayoutInfo + + Orientation + 2 + OutlineStyle + Basic + RowAlign + 1 + RowSpacing + 36 + SheetTitle + Master 1 + UniqueID + 1 + VPages + 1 + + + ModificationDate + 2012-01-24 17:14:19 -0500 + Modifier + classic + NotesVisible + NO + Orientation + 2 + OriginVisible + NO + OutlineStyle + Basic + PageBreaks + YES + PrintInfo + + NSBottomMargin + + coded + BAtzdHJlYW10eXBlZIHoA4QBQISEhAhOU051bWJlcgCEhAdOU1ZhbHVlAISECE5TT2JqZWN0AIWEASqEhAFklwCG + + NSLeftMargin + + coded + BAtzdHJlYW10eXBlZIHoA4QBQISEhAhOU051bWJlcgCEhAdOU1ZhbHVlAISECE5TT2JqZWN0AIWEASqEhAFklwCG + + NSPaperSize + + size + {612, 792} + + NSRightMargin + + coded + BAtzdHJlYW10eXBlZIHoA4QBQISEhAhOU051bWJlcgCEhAdOU1ZhbHVlAISECE5TT2JqZWN0AIWEASqEhAFklwCG + + NSTopMargin + + coded + BAtzdHJlYW10eXBlZIHoA4QBQISEhAhOU051bWJlcgCEhAdOU1ZhbHVlAISECE5TT2JqZWN0AIWEASqEhAFklwCG + + + ReadOnly + NO + RowAlign + 1 + RowSpacing + 36 + SheetTitle + Canvas 1 + SmartAlignmentGuidesActive + YES + SmartDistanceGuidesActive + YES + UniqueID + 1 + UseEntirePage + + VPages + 1 + WindowInfo + + CurrentSheet + 0 + DrawerOpen + + DrawerTab + Outline + DrawerWidth + 209 + FitInWindow + + Frame + {{335, 186}, {760, 817}} + ShowRuler + + ShowStatusBar + + VisibleRegion + {{-84, 0}, {745, 703}} + Zoom + 1 + + + diff --git a/docs/build/ops.rst b/docs/build/ops.rst index dc2cc4b..e9d5bf0 100644 --- a/docs/build/ops.rst +++ b/docs/build/ops.rst @@ -10,22 +10,28 @@ The directives here are used within user-defined migration files, within the ``upgrade()`` and ``downgrade()`` functions, as well as any functions further invoked by those. -A key design philosophy to the :mod:`alembic.op` functions is that +All directives exist as methods on a class called :class:`.Operations`. +When migration scripts are run, this object is made available +to the script via the ``alembic.op`` datamember, which is +a *proxy* to an actual instance of :class:`.Operations`. + +A key design philosophy to the :mod:`alembic.operations` methods is that to the greatest degree possible, they internally generate the appropriate SQLAlchemy metadata, typically involving :class:`~sqlalchemy.schema.Table` and :class:`~sqlalchemy.schema.Constraint` objects. This so that migration instructions can be given in terms of just the string names and/or flags involved. The exceptions to this -rule include the :func:`.op.add_column` and :func:`.op.create_table` +rule include the :meth:`~.Operations.add_column` and :func:`~.Operations.create_table` directives, which require full :class:`~sqlalchemy.schema.Column` objects, though the table metadata is still generated here. -The functions here all require that a :class:`.Context` has been -configured within the ``env.py`` script. Under normal circumstances -this is always the case, as the migration scripts are invoked via -the :func:`.context.run_migrations` function which ultimately -is derived from the :class:`.Context` object. +The functions here all require that a :class:`.MigrationContext` has been +configured within the ``env.py`` script first, which is typically +via :meth:`.EnvironmentContext.configure`. Under normal +circumstances they are called from an actual migration script, which +itself would be invoked by the :meth:`.EnvironmentContext.run_migrations` +method. .. automodule:: alembic.operations