Skip to content

Shell Support

Who never needed to load a few database models ina command line or have the need to do it so and got stuck trying to do it and wasted a lot of time?

Well, Saffier gives you that possibility completely out of the box and ready to use with your application models.


Be aware of the use of this special class in production! It is advised not to use it there.


Before reading this section, you should get familiar with the ways Saffier handles the discovery of the applications.

The following examples and explanations will be using the auto discovery but --app and environment variables approach but the is equally valid and works in the same way.


See the extras section after getting familiar with the previous. There offers a way of using the shell without going through the Migrate object.

How does it work

Saffier ecosystem is complex internally but simpler to the user. Saffier will use the application using the migration and automatically extract the registry from it.

From there it will automatically load the models and reflected models into the interactive python shell and load them for you with ease 🎉.


To run any of the available shells you will need ipython or ptpython or both installed.


$ pip install ipython


$ pip install saffier[ipython]


$ pip install ptpython


$ pip install saffier[ptpyton]

How to call it

With auto discovery

Default shell

$ saffier shell

PTPython shell

$ saffier shell --kernel ptpython

With --app and environment variables


$ saffier --app myproject.main:app shell

Environment variables

$ export SAFFIER_DEFAULT_APP=--app myproject.main:app
$ saffier shell --kernel ptpython

How does it look like

Saffier doesn't want to load all python globals and locals for you. Instead loads all the essentials for the models and reflected models and some python packages.

It looks like this:

Shell Example

Of course the SAFFIER-VERSION and APPLICATION are replaced automatically by the version you are using.


Let us see an example using example using Esmerald and we will have:

And it will look like this:

Shell Example

Pretty cool, right? Then it is a normal python shell where you can import whatever you want and need as per normal python shell interaction.