Skip to content


Who never had that feeling that sometimes haing some database settings would be nice? Well, since Saffier is from the same author of Esmerald and since Esmerald is settings oriented, why not apply the same principle but in a simpler manner but to Saffier?

This is exactly what happened.

Saffier Setting Module

The way of using the settings object within a Saffier use of the ORM is via:

  • SAFFIER_SETTINGS_MODULE environment variable.

All the settings are pydantic BaseSettings objects which makes it easier to use and override when needed.


Saffier by default uses is looking for a SAFFIER_SETTINGS_MODULE environment variable to run and apply the given settings to your instance.

If no SAFFIER_SETTINGS_MODULE is found, Saffier then uses its own internal settings which are widely applied across the system.

Custom settings

When creating your own custom settings class, you should inherit from SaffierSettings which is the class responsible for all internal settings of Saffier and those can be extended and overriden with ease.

Something like this:

from typing import Optional

from saffier import SaffierSettings
from saffier.conf.enums import EnvironmentType

class MyCustomSettings(SaffierSettings):
    My settings overriding default values and add new ones.

    environment: Optional[str] = EnvironmentType.TESTING

    # new settings
    my_new_setting: str = "A text"

Super simple right? Yes and that is the intention. Saffier does not have a lot of settings but has some which are used across the codebase and those can be overriden easily.


Be careful when overriding the settings as you might break functionality. It is your own risk doing it.

  • ipython_args - List of arguments passed to ipython when starting the saffier shell.

    Default: ["--no-banner"]

  • ptpython_config_file - Config file to be loaded into ptpython when starting the saffier shell --kernel ptpython.

    Default: "~/.config/ptpython/"

  • postgres_dialects - Set of available Postgres dialects supported by Saffier.

    Default: {"postgres", "postgresql"}

  • mysql_dialects - Set of available MySQL dialects supported by Saffier.

    Default: {"mysql"}

  • sqlite_dialects - Set of available SQLite dialects supported by Saffier.

    Default: {"sqlite"}

  • mssql_dialects - Set of available MSSQL dialects supported by Saffier.

    Default: {"mssql"}

  • postgres_drivers - Set of available Postgres drivers supported by Saffier.

    Default: {"aiopg", "asyncpg"}

  • mysql_drivers - Set of available MySQL drivers supported by Saffier.

    Default: {"aiomysql", "asyncmy"}

  • sqlite_drivers - Set of available SQLite drivers supported by Saffier.

    Default: {aiosqlite}

How to use it

Similar to esmerald settings, Saffier uses it in a similar way.

Using the example above and the location myproject/configs/, the settings should be called like this:

$ SAFFIER_SETTINGS_MODULE=myproject.configs.settings.MyCustomSettings saffier <COMMAND>


Starting the default shell

$ SAFFIER_SETTINGS_MODULE=myproject.configs.settings.MyCustomSettings saffier shell

Starting the PTPython shell

$ SAFFIER_SETTINGS_MODULE=myproject.configs.settings.MyCustomSettings saffier shell --kernel ptpython

Creating the migrations folder

$ SAFFIER_SETTINGS_MODULE=myproject.configs.settings.MyCustomSettings saffier init

Generating migrations

$ SAFFIER_SETTINGS_MODULE=myproject.configs.settings.MyCustomSettings saffier makemigrations

Appying migrations

$ SAFFIER_SETTINGS_MODULE=myproject.configs.settings.MyCustomSettings saffier migrate

And the list goes on and on, you get the gist. To understand which commands are available, check the commands available to you and the shell support for the Saffier shell support.