Alembic does have a comprehensive userguide available here.
However, it requires to install python on our computer and SqlAlchemy.
In this company, as in most company in the world, we are using Windows... so, let's have a look to the installation process.
Installing Python 3 for Windows
That operation is quite easy, just browse the site www.python.org/downloads/windows/ a download the latest version of Python.
At the time of this article, we did installed Python 3.4.3 to have full unicode support.
Installing PIP - Python Package Installer for Windows
As far I know, this utilitity is now distributed along with Python3.x for Windows.
In my recollection, I didn't install it.
The only think to know about it is its executable is not named "
So any package installation under Python3 is done with "pip3 install ..."
Installing PSYCOPG2 under Windows
PSYCOPG is the most popular Python DB API 2.0 for Python.
To install it with PIP tool, you need to have the VC compiler 10 on your computer.
That's weird! Windows is not distributed with a native compiler... and I'm using VC compiler V9 for my HarbourProject developement. So I can't rely on PIP!
The other solution is to use a "PsycoPg2 Windows Installer" which contains the needed binaries.
If you are willing to do so, you must install the PSYCOPG2. Just choose the version according to python language (I'm using Pyhton 3.4)
It even exists a Windows Installer for Window... you will find them on win-psycopg
The drawback of Windows Installer approach is that we can't install the PSYCOPG2 inside a Python virtual environment (windows installer doesn't take care of it).
So we have to install it on at the system level (said "site-package") and then before we do initiate a virtual environment.
Installing Python VirtualEnv under Windows
Presenting Virtual Env
VirtualEnv is a tool that you must absolutely know and use as soon as possible.
This tool will become your best friend and save you lot of worries.
Virtual Environment allows you to create isolated python environment (named "virtual environnement" or "VirtualEnv" for short) and install every package you want into this isolated environment without putting the mess on your regular system or other virtual environment.
You can create as many virtual environement as you which... they are stored into sub-folder on the file system.
To use a "virtual environment", you navigate into the target sub-folder and activate the environment by calling an activation script.
If you ruine something in your Virtual Environement, you just get out of it (deactivate it), drop it (so drop a sub-folder), and create a new one where you can try to catch what goes wrong with the installed/upgraded packages. But your system is safe... NO MESS :-)
Everybody knows what the hell a wrong version of library can do in your software... and how it could be difficult to revert the installation process.
Installing VirtualEnv for Windows
Just type the following command under the command prompt
pip3 install virtualenv
and wait the installation process to get completed.
Creating our sqlachemy-test virtual environment
On my Windows computer, I did created the c:\python folder to store all my python development projects.
I will create & activate the "sqlalchemy-test" virtual environment to test Alembic database upgrade without putting the mess on the computer.
By creating the "sqlalchemy-test" virtual environment, we will create a sqlaclchemy-test subfolder.
cd c:\python virtualenv --system-site-packages sqlalchemy-test
The command line includes the parameter system-site-packages which is very important in this case.
This would make the psycopg2 available in the virtual environment (otherwise SqlAlchemy will crash because it would not be possible to import the psycopg2 package)
 |
| the "sqlalchemy-test" virtual environment is contained within the "sqlalchemy-subfolder" |
Just go inside the sqlalchemy-test subfolder and call the activation script/batch.
c:\>cd c:\Python\sqlalchemy-test c:\Python\sqlalchemy-test>.\Scripts\activate (sqlalchemy-test) c:\Python\sqlalchemy-test>
Need to deactivate the virtual environment?
Just use the .\Scripts\deactivate on a command line instead of the
Installing SQLAlchemy
SqlAlchemy is the prerequisite for Alembic... so we will install it.
Since we did created and activated the sqlalchemy-test virtual environment we don't have to take care about overwriting a system package.
We don't have to be afraid to put the mess... we did created and activated an isolated environment.
pip3 install sqlalchemy
>>> import sqlalchemy >>> sqlalchemy.__version__ '1.0.8'
Installing Alembic
Now, we will install Alembic with the following pip command.
pip3 install alembic
Checking the installation is as simple as ...
(sqlalchemy-test) c:\Python\sqlalchemy-test>python Python 3.4.3 (v3.4.3:9b73f1c3e601, Feb 24 2015, 22:43:06) [MSC v.1600 32 bit tel)] on win32 Type "help", "copyright", "credits" or "license" for more information. >>> import alembic >>> alembic.__version__ '0.8.2'
What to do now?
Just follow the "Alembic documentation" and learn how to use it.
Ressource
SqlAlchemy
Alembic
VirtualEnvWrapper-Powershell
It also exists advanced VirtualEnv tools (VirtualEnvWrapper-powershell) that may help you to manage higher level operation with VirtualEnv (like copying, switching, checking, etc) from Windows PowerShell.
If you are interested, please read the following article:
