Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
---
title: Database Configuration
description: Learn how to configure Spree to work with PostgreSQL, MySQL, or SQLite.
canonical: "https://spreecommerce.org/docs/developer/deployment/database"
---
## 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:
```bash
# 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](/v5/developer/deployment/background_jobs) threads, since jobs run inside the web container by default:
<Tabs>
<Tab title="PostgreSQL">
```yaml
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"] %>
```
</Tab>
<Tab title="MySQL">
```yaml
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"] %>
```
</Tab>
<Tab title="SQLite">
```yaml
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
```
</Tab>
</Tabs>
## Switching Databases
The easiest way to switch your existing Spree application to a different database is using the built-in Rails command:
```bash
# 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:
1. Install the new gem:
```bash
bundle install
```
2. Create the new database and run migrations:
```bash
bin/rails db:create db:migrate
```
3. Optionally load sample data:
```bash
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`:
```bash
# 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.