Database Configuration

Supported Databases

Database	Development	Production	Notes
PostgreSQL	Yes	Yes	Recommended for production. Best performance for large catalogs and high traffic
MySQL	Yes	Yes	Fully supported. A great choice if your team already uses MySQL
SQLite	Yes	Yes	Zero-configuration setup. Ideal for development, small stores, and getting started quickly

Configuring Your Database

Using DATABASE_URL

The simplest way to configure your database is via the DATABASE_URL environment variable:

# PostgreSQL
DATABASE_URL=postgres://user:pass@localhost:5432/spree

# MySQL
DATABASE_URL=mysql2://user:pass@localhost:3306/spree

# SQLite
DATABASE_URL=sqlite3:db/production.sqlite3

Using database.yml

You can also configure the database in config/database.yml. The connection pool is sized to cover web request threads plus background job threads, since jobs run inside the web container by default:

PostgreSQL
MySQL
SQLite

default: &default
  adapter: postgresql
  encoding: unicode
  pool: <%= Integer(ENV.fetch("RAILS_MAX_THREADS", 3)) + Integer(ENV.fetch("JOB_THREADS", 3)) + 3 %>

development:
  <<: *default
  database: spree_development

production:
  <<: *default
  database: spree_production
  url: <%= ENV["DATABASE_URL"] %>

default: &default
  adapter: mysql2
  encoding: utf8mb4
  pool: <%= Integer(ENV.fetch("RAILS_MAX_THREADS", 3)) + Integer(ENV.fetch("JOB_THREADS", 3)) + 3 %>

development:
  <<: *default
  database: spree_development

production:
  <<: *default
  database: spree_production
  url: <%= ENV["DATABASE_URL"] %>

default: &default
  adapter: sqlite3
  pool: <%= Integer(ENV.fetch("RAILS_MAX_THREADS", 3)) + Integer(ENV.fetch("JOB_THREADS", 3)) + 3 %>
  timeout: 5000

development:
  <<: *default
  database: db/development.sqlite3

production:
  <<: *default
  database: db/production.sqlite3

Switching Databases

The easiest way to switch your existing Spree application to a different database is using the built-in Rails command:

# Switch to PostgreSQL
bin/rails db:system:change --to=postgresql

# Switch to MySQL
bin/rails db:system:change --to=mysql

# Switch to SQLite
bin/rails db:system:change --to=sqlite3

This command will:

Update your Gemfile with the correct database gem
Generate a new config/database.yml configured for the selected database

After running the command, complete the switch:

Install the new gem:
bundle install
Create the new database and run migrations:
bin/rails db:create db:migrate
Optionally load sample data:
bin/rails spree_sample:load

Creating a New App with a Specific Database

When creating a new Spree application with the manual installation method, pass the -d flag to rails new:

# PostgreSQL
rails new my_store -d postgresql -m https://raw.githubusercontent.com/spree/spree/main/spree/template.rb

# MySQL
rails new my_store -d mysql -m https://raw.githubusercontent.com/spree/spree/main/spree/template.rb

# SQLite (default, no flag needed)
rails new my_store -m https://raw.githubusercontent.com/spree/spree/main/spree/template.rb

Cloud Database Services

For production deployments, you can use managed database services:

Provider	PostgreSQL	MySQL
AWS	RDS PostgreSQL, Aurora PostgreSQL	RDS MySQL, Aurora MySQL, RDS MariaDB
Google Cloud	Cloud SQL for PostgreSQL	Cloud SQL for MySQL
Azure	Azure Database for PostgreSQL	Azure Database for MySQL
Heroku	Heroku Postgres	JawsDB, ClearDB
Render	Render PostgreSQL	—

Set the DATABASE_URL environment variable to the connection string provided by your cloud provider.

Deployment

Upgrading

Contributing

Security

Supported Databases

Configuring Your Database

Using DATABASE_URL

Using database.yml

Switching Databases

Creating a New App with a Specific Database

Cloud Database Services

​Supported Databases

​Configuring Your Database

​Using DATABASE_URL

​Using database.yml

​Switching Databases

​Creating a New App with a Specific Database

​Cloud Database Services

Supported Databases

Configuring Your Database

Using DATABASE_URL

Using database.yml

Switching Databases

Creating a New App with a Specific Database

Cloud Database Services