SQLAlchemy Python tutorial

SQLAlchemy is one of the most widely used object-relational mapping tools in the Python community. It is the Python SQL toolkit and Object Relational Mapper that gives application developers the full power and flexibility of SQL. More details about SQLAlchemy are available at SQLAlchemy.org.

The FairCom SQL Python interface provides support for this technology.

If you have an existing application that uses SQLAlchemy, simply install the FairCom SQL dialect for SQLAlchemy to begin using the FairCom database.

If you are planning a new SQLAlchemy application, FairCom SQLAlchemy support enables you to take advantage of this powerful programming style.

FairCom also supports Python through a SQL Python interface.

FairCom recommends that the tutorials for the Python APIs be run using Python version 3 - preferably version 3.4+. Accordingly, in the instructions below, we have made the following assumptions about how the user's machine is configured:

Windows: The PATH should be configured so that invoking Python at the command-line will run version 3 of Python and invoking pip at the command-line will run the instance of pip that is associated with that version of Python.

Linux: The system should be configured so that invoking python3 at the command-line will run version 3 of Python, and invoking pip3 at the command-line will run the instance of pip that is associated with that version of Python.

These assumptions are also made by the batch files (Windows) and make files (Linux) that FairCom provides to run the tutorials. Users must configure their machines to match the assumptions. Alternatively, you can modify the instructions in the batch or make files that follow to match the machine's configuration.

Bit Depth: The bit depth of the Python version 3 you are using must match the bit depth of the FairCom product you are using.

Windows:

Linux:

If any steps have permission problems, use sudo to run that command.

If you get the following error:

setuptools_scm.version.SetuptoolsOutdatedWarning: your setuptools is too old (>12)

You must un-install the old version of the Python setuptools package and install a later version, as follows:

After updating setuptools, try again.

To run the tutorial, use the batch file (Windows) or make file (Linux) in the <faircom>\drivers\python.sql.sqlalchemy\tutorials\cmdline folder:

cd tutorials\cmdline

Windows: 

BuildTutorials.bat

Linux: 

make build; make run

On Linux, the build command copies a library to the correct location and the run command runs the tutorial.

The tutorial should print the following:

<User(id='1', name='u1')>
[<Address(email='one')>, <Address(email='two')>]

Problem: "ImportError: No module named setuptools"

Solution: Install setuptools.

Problem: "pyctree missing"

Solution: Be sure you have installed pyctree.

Problem: sql.sqlalchemy can fail with "shared library not found."

Solution: Run one of the following:

The Python tutorials currently use “127.0.0.1” to connect to the FairCom server on the local machine instead of using “localhost”. This is because Windows 10 often has “localhost” commented out of its “hosts” file (%systemroot%\System32\drivers\etc\hosts), as follows:

# localhost name resolution is handled within DNS itself.
#127.0.0.1 localhost
#::1 localhost

Unfortunately, Python does not seem to use DNS to resolve "localhost". This means that these tutorials cannot connect to the FairCom server on some versions of Windows if they use “localhost” instead of “127.0.0.1”. We use “127.0.0.1” in our Python tutorials to work around this problem.

If you are using IPv6, or have some other situation where “127.0.0.1” is not appropriate, feel free to update the call to create_engine() in the demonstration file, <faircom>\drivers\python.sql.sqlalchemy\tutorials\usage.py