Using Databases

As Sqlite is file-based, Chipper CI comes with Sqlite support.

The following can be configured to be used within a build:


  • MySQL (5.6, 5.7, 8)
  • MariaDB (10.3)
  • PostgreSQL (10, 11, 12, 13, 14)
    • PostgreSQL with Postgis also available


  • Redis

Build Spec

Here's what each option looks like in the .chipperci.yml file:

  - mysql: 5.7    # 5.6, 5.7, 8
  - postgres: 13  # 10, 11, 12, 13, 14
  - postgis/postgis: 13-3.0  # 10-3.0, 11-3.0, 12-3.0, 13-3.0, 14-3.0
  - redis:        # Be sure to include the trailing colon. This always uses "latest". 

You can only use one database per project. You can use redis alongside any database. This is valid, for example:

  - mysql: 5.7
  - redis: 

Environment Variables

When using a database/cache, the following environment variables are set as system variables within the build container:

For MySQL/MariaDB:

The following MySQL-specific environment variables are set:

  • MYSQL_HOST = mysql
  • MYSQL_PORT = 3306
  • MYSQL_DATABASE = chipperci
  • MYSQL_USER = chipperci
  • MYSQL_PASSWORD = secret

For PostgreSQL (including postgis):

The following PostgreSQL-specific environment variables are set:

  • POSTGRES_HOST = postgres
  • POSTGRES_PORT = 5432
  • POSTGRES_DB = chipperci (a database created for you)
  • POSTGRES_USER = chipperci

For Laravel:

The following Laravel-specific environment variables are set if you select a MySQL or PostgreSQL database.

Note that this means you don't need to define these yourself within a .env/.env.testing nor phpunit.xml file.

  • DB_CONNECTION = mysql || pgsql
  • DB_HOST = mysql || mariadb || postgres
  • DB_PORT = 3306 || 5432
  • DB_DATABASE = chipperci
  • DB_USERNAME = chipperci
  • DB_PASSWORD = secret

For PostgreSQL, the DB_CONNECTION will be named pgsql, which is Laravel's default for PostgreSQL connections. The DB_HOST will be postgres.

For Redis:

The following are used by Laravel and also happen to follow Chipper's environment variable naming convention.

  • REDIS_HOST = redis
  • REDIS_PORT = 6379

Available Database Commands

The build container contains the following database command-line clients:

  1. mysql
  2. psql
  3. redis-cli

The build container is setup so you do NOT need to pass a username (and you will you be prompted for a password) for any client commands.

That being said, there are the above environment variables defined for you to use if you need. For example, you may want to create an additional MySQL/MariaDB database (the build container creates one for you by default):

# The `mysql` command is run as root, so make sure to give
# user $MYSQL_USER permissions to any new database
mysql -e "create database foo charset utf8mb4;"
# Be sure to use "with grant option" to get full permissions
mysql -e "grant all privileges on *.* to '$MYSQL_USER'@'%' with grant option;";

# You can run commands in PostgreSQL as well:
PGPASSWORD=$DB_PASSWORD psql -h $DB_HOST -U $DB_USERNAME -c "create database foo;"

Some like to import a database dump prior to running tests. The available database commands can help you do that as well. For example, to dump a .sql file into MySQL, you may want to use a command similar to this:

# Import a .sql file
mysql $DB_DATABASE < tests/my_database.sql

# Import a .sql.gz file (decompress via gzip, then pipe to mysql)
gunzip < my_database.sql.gz | mysql $DB_DATABASE