What is DATABASE_URL?

The DATABASE_URL is a standardized environment variable that follows RFC 3986. It is way to specify database connection details and is commonly used in various deployment environments and hosting platforms.

DATABASE_URL contains a URL string with information needed to connect to a database. This URL includes details like the database type (e.g., PostgreSQL, MySQL), the host, port, database name, and authentication credentials.

There are three types supported by the application:

  1. SQLite3: this is ephemeral and lost on container restart
  2. PostgreSQL: The Postgres Database - persistent
  3. Mysql (or MariaDB): Persistent

Remember to replace the placeholders in these examples (e.g., username, password, hostname, port, database_name) with the actual credentials and database information for your specific setup.

Note: Options can be provided with the DATABASE_URL by adding ?option1=value1&option2=value2 to the end of the URL.

SQLite3

Note: SQLite3 is the default database type. If DATABASE_URL is not specified, it will default to this ephemeral backend storage.

For SQLite3, the DATABASE_URL typically looks like this:

sqlite3:db/db.sqlite3

  • sqlite3:// is the protocol.
  • db/db.sqlite3 is the path to your SQLite database file.

Warning: This database type is lost on container restart. This is desired by some for simplicity and security. If you want to persist this database file, see How to Persist the Ephemeral Database across Container Restarts

Example

sqlite3:///opt/PasswordPusher/db/db.sqlite3

PostgreSQL

For PostgreSQL, the DATABASE_URL follows this format:

postgres://username:password@hostname:port/database_name
  • postgres:// is the protocol.
  • username:password are your PostgreSQL credentials.
  • hostname is the host where your PostgreSQL database is running.
  • port is the port number for the database (typically 5432).
  • database_name is the name of your PostgreSQL database.

Warning: hostname values with underscores are not supported. See #1602

Example

   postgres://myuser:mypassword@localhost:5432/mydatabase

MySQL

For MySQL, the DATABASE_URL format is similar to PostgreSQL:

mysql2://username:password@hostname:port/database_name
  • mysql2:// is the protocol.
  • username:password are your MySQL credentials.
  • hostname is the MySQL server host.
  • port is the MySQL server port (typically 3306).
  • database_name is the name of your MySQL database.

Warning: hostname values with underscores are not supported. See #1602

Example

mysql2://myuser:mypassword@localhost:3306/mydatabase

Note: SSL mode can be enabled by adding ssl_mode=required to the end of the URL.

mysql2://myuser:mypassword@localhost:3306/mydatabase?ssl_mode=required

MariaDB

MariaDB is compatible with MySQL, so the DATABASE_URL format for MariaDB is the same as for MySQL:

mysql2://username:password@hostname:port/database_name
  • mysql2:// is the protocol.
  • username:password are your MariaDB credentials.
  • hostname is the MariaDB server host.
  • port is the MariaDB server port (typically 3306).
  • database_name is the name of your MariaDB database.

Warning: hostname values with underscores are not supported. See #1602

Example

mysql2://myuser:mypassword@localhost:3306/mydatabase

Note: SSL mode can be enabled by adding ssl_mode=required to the end of the URL.

mysql2://myuser:mypassword@localhost:3306/mydatabase?ssl_mode=required

Valid Characters

The Database URI described on this page follows RFC 3986 which has a limited set of characters that can be used in the URI.

You can read the RFC (which isn’t much fun) but generally, the characters that are not allowed in username, password, host or database are:

%^#_:

Admittedly this is a bit of a headache even for me. This is an internet standard. Not something I’ve introduced.

If you keep _ out of the database hostname and the characters %^#_: out of passwords, you should be fine.

Tip: See this regex tool to test your string with RFC3986.

See Also

Updated: