Documentation Index
Fetch the complete documentation index at: /docs/llms.txt
Use this file to discover all available pages before exploring further.
Skip to main contentSupported 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:
default: &default
adapter: postgresql
encoding: unicode
pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
development:
<<: *default
database: spree_development
production:
<<: *default
database: spree_production
url: <%= ENV["DATABASE_URL"] %>
default: &default
adapter: mysql2
encoding: utf8mb4
pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
development:
<<: *default
database: spree_development
production:
<<: *default
database: spree_production
url: <%= ENV["DATABASE_URL"] %>
default: &default
adapter: sqlite3
pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
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
- 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:
-
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 | — |
DATABASE_URL environment variable to the connection string provided by your cloud provider.Responses are generated using AI and may contain mistakes.
