Supported types

The following are all type-casting methods of environ.Env.

environ.Env.dict

environ.Env may parse complex variables like with the complex type-casting. For example:

 import environ


 env = environ.Env()

 # {'key': 'val', 'foo': 'bar'}
 env.parse_value('key=val,foo=bar', dict)

 # {'key': 'val', 'foo': 1.1, 'baz': True}
 env.parse_value(
     'key=val;foo=1.1;baz=True',
     dict(value=str, cast=dict(foo=float,baz=bool))
)

For more detailed example see “Complex dict format”.

environ.Env.db_url

db_url() supports the following URL schemas:

Amazon Redshift

Database Backend: django_redshift_backend

URL schema: redshift://

LDAP

Database Backend: ldapdb.backends.ldap

URL schema: ldap://host:port/dn?attrs?scope?filter?exts

MSSQL

Database Backend: sql_server.pyodbc

URL schema: mssql://user:password@host:port/dbname

With MySQL you can use the following schemas: mysql, mysql2.

MySQL (GIS)

Database Backend: django.contrib.gis.db.backends.mysql

URL schema: mysqlgis://user:password@host:port/dbname

MySQL

Database Backend: django.db.backends.mysql

URL schema: mysql://user:password@host:port/dbname

MySQL Connector Python from Oracle

Database Backend: mysql.connector.django

URL schema: mysql-connector://

Oracle

Database Backend: django.db.backends.oracle

URL schema: oracle://user:password@host:port/dbname

PostgreSQL

Database Backend: django.db.backends.postgresql

URL schema: postgres://user:password@host:port/dbname

With PostgreSQL you can use the following schemas: postgres, postgresql, psql, pgsql, postgis. You can also use UNIX domain sockets path instead of hostname. For example: postgres://path/dbname. The django.db.backends.postgresql_psycopg2 will be used if the Django version is less than 2.0.

PostGIS

Database Backend: django.contrib.gis.db.backends.postgis

URL schema: postgis://user:password@host:port/dbname

PyODBC

Database Backend: sql_server.pyodbc

URL schema: pyodbc://

SQLite

Database Backend: django.db.backends.sqlite3

URL schema: sqlite:////absolute/path/to/db/file

SQLite connects to file based databases. URL schemas sqlite:// or sqlite://:memory: means the database is in the memory (not a file on disk).

SpatiaLite

Database Backend: django.contrib.gis.db.backends.spatialite

URL schema: spatialite:///PATH

SQLite connects to file based databases. URL schemas sqlite:// or sqlite://:memory: means the database is in the memory (not a file on disk).

Database query options in db_url

Query parameters from DATABASE_URL are mapped to Django database settings:

  • known base keys (for example conn_max_age, autocommit, atomic_requests) are promoted to top-level DB config keys;

  • all other query params are stored in OPTIONS.

For MySQL strict mode, for example:

DATABASE_URL=mysql://user:password@host:3306/dbname?sql_mode=STRICT_TRANS_TABLES

This produces:

{"OPTIONS": {"sql_mode": "STRICT_TRANS_TABLES"}}

If a value needs explicit typing (for example booleans or JSON), use options_cast with an explicit URL and expected result:

import json
import environ

url = (
    "mysql://user:password@host:3306/dbname?"
    "reconnect=true&ssl=%7B%22ca%22%3A%22%2Fapp%2Ffoo%2Fca.pem%22%7D"
)
config = environ.Env.db_url_config(
    url,
    options_cast={
        "reconnect": bool,
        "ssl": json.loads,
    }
)

# {"OPTIONS": {"reconnect": True, "ssl": {"ca": "/app/foo/ca.pem"}}}

Only mapped keys are cast with the provided type/callable. Unmapped options keep the default parsing behavior.

For values that are not practical to pass in a URL query string (for example nested dictionaries like Django 5.1 PostgreSQL pool options), pass extra_options and they will be merged into OPTIONS:

config = environ.Env.db_url_config(
    "postgres://user:password@host:5432/dbname",
    extra_options={
        "pool": {"min_size": 2, "max_size": 4, "timeout": 10},
    },
)

# {"OPTIONS": {"pool": {"min_size": 2, "max_size": 4, "timeout": 10}}}

environ.Env.cache_url

cache_url() supports the following URL schemas:

  • Database: dbcache://

  • Dummy: dummycache://

  • File: filecache://

  • Memory: locmemcache://

  • Memcached:

    • memcache:// (uses python-memcached backend, deprecated in Django 3.2)

    • pymemcache:// (uses pymemcache backend if Django >=3.2 and package is installed, otherwise will use pylibmc backend to keep config backwards compatibility)

    • pylibmc://

  • Redis: rediscache://, redis://, or rediss://

  • Valkey: valkey://, or valkeys://

environ.Env.search_url

search_url() supports the following URL schemas:

  • Elasticsearch: elasticsearch:// (http) or elasticsearchs:// (https)

  • Elasticsearch2: elasticsearch2:// (http) or elasticsearch2s:// (https)

  • Elasticsearch5: elasticsearch5:// (http) or elasticsearch5s:// (https)

  • Elasticsearch7: elasticsearch7:// (http) or elasticsearch7s:// (https)

  • Solr: solr://

  • Whoosh: whoosh://

  • Xapian: xapian://

  • Simple cache: simple://

environ.Env.email_url

email_url() supports the following URL schemas:

  • SMTP: smtp://

  • SMTP+SSL: smtp+ssl://

  • SMTP+TLS: smtp+tls://

  • Console mail: consolemail://

  • File mail: filemail://

  • LocMem mail: memorymail://

  • Dummy mail: dummymail://