Skip to main content
Version: Next

Configure database backends

This guide provides instructions on configuring new database backends or changing the existing database backend within your existing Marten projects.

Context​

Marten officially supports MariaDB, MySQL, PostgreSQL, and SQLite3 databases. New Marten projects default to utilizing a SQLite3 database, a lightweight serverless database application that is typically pre-installed on most existing operating systems. This makes it an excellent choice for a development or testing database, but you may want to use a more powerful database such as MariaDB, MySQL, or PostgreSQL. In this light, this guide explains what steps should be taken in order to use your database backend of choice in a Marten project.

Prerequisites​

This guide presupposes that you already have a functional Marten project available. If you don't, you can easily create one using the following command:

marten new project

Furthermore, it assumes that your preferred database is properly configured and ready for use. If this isn't the case, please consult the respective official documentation to install your chosen database:

Installing the right database shard​

For each database, a dedicated Crystal shard is required. Depending on your chosen database, you must include one of the following entries in your project's shard.yml file:

This means that your shard.yml file should resemble one of the following examples:

MariaDB or MySQL​

name: myproject
version: 0.1.0

dependencies:
  marten:
    github: martenframework/marten
  mysql:
    github: crystal-lang/crystal-mysql

PostgreSQL​

name: myproject
version: 0.1.0

dependencies:
  marten:
    github: martenframework/marten
  pg:
    github: will/crystal-pg

SQLite3​

name: myproject
version: 0.1.0

dependencies:
  marten:
    github: martenframework/marten
  sqlite3:
    github: crystal-lang/crystal-sqlite3

Adding the right DB Crystal requirement​

After you've included the correct Crystal shard in your project's shard.yml file, the subsequent task is to add the corresponding requirement in the src/project.cr file. This file contains all the requirements of your project (including Marten itself) and is automatically generated by the new management command.

Please consult the examples below to determine which requirement you should include based on your selected database backend:

MariaDB or MySQL​

# Third party requirements.
require "marten"
require "mysql"

# Project requirements.
# [...]

# Configuration requirements.
# [...]

PostgreSQL​

# Third party requirements.
require "marten"
require "pg"

SQLite3​

# Third party requirements.
require "marten"
require "sqlite3"

Configuring your database​

The last step involves configuring database settings so that they target the database you intend to use with your Marten project. While a comprehensive list of configuration options is available in the Database settings reference, the following sections offer example configurations tailored to each supported database backend.

MariaDB or MySQL​

config.database do |db|
  db.backend = :mysql
  db.host = "localhost"
  db.name = "my_db"
  db.user = "my_user"
  db.password = "insecure"
end

PostgreSQL​

config.database do |db|
  db.backend = :postgresql
  db.host = "localhost"
  db.name = "my_db"
  db.user = "my_user"
  db.password = "insecure"
end

SQLite3​

config.database do |db|
  db.backend = :sqlite
  db.name = "my_db.db"
end

Using URLs​

# Configure db using just a URL
config.database url: "postgres://my_user:my_db@localhost:1234/db"

# Configure a db other than the default using just a URL
config.database url: "postgres://my_user:my_db@localhost:1234/db"
config.database :my_other_db, url: "sqlite://my_other.db?journal_mode=wal&synchronous=normal"

# Configure db with a URL and a block
config.database url: "postgres://my_user:my_db@localhost:1234/db" do |db|
  db.retry_delay = 1.0
end

# Configure a db other than the default with a URL and a block
config.database :my_other_db, url: "sqlite://my_other.db" do |db|
  db.options = {
    "journal_mode" => "wal"
    "synchronous" => "normal"
  }
end