Configurar la BBDD en Ruby on Rails: database.yml
Para configurar la base de datos (BBDD) en Ruby on Rails se edita un único fichero, config/database.yml. Ahí le dices a Rails qué base de datos usar (SQLite, PostgreSQL o MySQL), en qué máquina está y con qué usuario entrar, y puedes darle una configuración distinta a cada entorno.
Esta guía cubre los tres casos habituales: SQLite, que viene por defecto en Rails 8; PostgreSQL, en un proyecto nuevo o cambiando desde SQLite, y MySQL. Casi todo el código se ha ejecutado, con Rails 8.1.4.1, Ruby 4.0.9 y PostgreSQL 18.6, y las salidas son reales; la parte de MySQL no se ha probado contra un servidor, y se indica.
Cómo funciona config/database.yml
El archivo de configuración está en config/database.yml. Así se veía en la versión original de este artículo, con Rails 5.2:
# SQLite version 3.x
# gem install sqlite3
#
# Ensure the SQLite 3 gem is defined in your Gemfile
# gem 'sqlite3'
#
default: &default
adapter: sqlite3
pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
timeout: 5000
development:
<<: *default
database: db/development.sqlite3
# Warning: The database defined as "test" will be erased and
# re-generated from your development database when you run "rake".
# Do not set this db to the same as development or production.
test:
<<: *default
database: db/test.sqlite3
production:
<<: *default
database: db/production.sqlite3
Hay una configuración para cada entorno, que es el modo en el que arranca la aplicación:
| Entorno | Para qué sirve |
|---|---|
development |
Mientras programas en tu ordenador |
test |
Cuando ejecutas los tests. Esta base de datos se borra y se regenera, así que nunca uses la misma que en desarrollo o producción |
production |
La aplicación publicada, con los datos reales |
El bloque default: &default guarda la configuración común, y cada entorno la reutiliza con <<: *default. Es como una plantilla de formulario: la rellenas una vez con lo que es igual para todos (el adaptador, la codificación, el número de conexiones) y cada entorno la copia y solo cambia lo suyo, normalmente el nombre de la base de datos.
Las claves que verás más a menudo:
| Clave | Qué indica |
|---|---|
adapter |
El tipo de base de datos: sqlite3, postgresql, mysql2 o trilogy |
database |
El nombre de la base de datos (en SQLite, la ruta del fichero) |
host, port |
Dónde está el servidor. Si no pones host, PostgreSQL y MySQL intentan conectar por un socket local |
username, password |
Con qué usuario entrar |
max_connections |
Cuántas conexiones puede abrir cada proceso. En versiones anteriores se llamaba pool, que sigue funcionando |
encoding |
La codificación de texto: unicode en PostgreSQL, utf8mb4 en MySQL |
El fichero admite etiquetas ERB (<%= %>): lo que va dentro se ejecuta como Ruby. Así se leen las variables de entorno, como <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>, que usa la variable si existe y, si no, el valor 5.
SQLite: la base de datos por defecto en Rails 8
Si creas un proyecto con rails new sin indicar nada, Rails usa SQLite. Es una base de datos que se guarda en un fichero y no necesita instalar ni arrancar ningún servidor. La guía oficial lo explica así: Rails la elige por defecto porque no requiere configuración, y siempre puedes cambiarla después.
Este es el config/database.yml que genera Rails 8.1.4.1, sin los comentarios:
default: &default
adapter: sqlite3
max_connections: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
timeout: 5000
development:
<<: *default
database: storage/development.sqlite3
test:
<<: *default
database: storage/test.sqlite3
Debajo viene un bloque production con cuatro bases de datos (primary, cache, queue y cable), que Rails 8 usa para la caché, las tareas en segundo plano y los websockets.
Crear la base de datos y aplicar una migración, en un proyecto con un modelo Libro:
bin/rails db:create db:migrate
Created database 'storage/development.sqlite3'
Created database 'storage/test.sqlite3'
== 20261109010244 CreateLibros: migrating =====================================
-- create_table(:libros)
-> 0.0036s
== 20261109010244 CreateLibros: migrated (0.0037s) ============================
Los ficheros aparecen en storage/, no en db/ como en versiones antiguas. La guía oficial avisa de que, aunque Rails ya prepara SQLite para producción, un entorno de producción con mucha carga puede desbordarla. Por eso muchos proyectos pasan a PostgreSQL o MySQL al crecer.
Configurar PostgreSQL en Rails
En un proyecto nuevo
Indica la base de datos al crear el proyecto con -d (o --database):
rails new tienda -d postgresql
Rails añade la gema pg al Gemfile (gem "pg", "~> 1.1") y escribe este config/database.yml (sin comentarios):
default: &default
adapter: postgresql
encoding: unicode
max_connections: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
development:
<<: *default
database: tienda_development
test:
<<: *default
database: tienda_test
production:
primary: &primary_production
<<: *default
database: tienda_production
username: tienda
password: <%= ENV["TIENDA_DATABASE_PASSWORD"] %>
# ... y los bloques cache, queue y cable
Fíjate en dos cosas. En desarrollo no hay host, username ni password: Rails da por hecho que PostgreSQL está en tu máquina y que entras con tu usuario del sistema por un socket local. Y en producción la contraseña ya sale de una variable de entorno, no del fichero.
La gema pg se instala como gema binaria, con la librería cliente de PostgreSQL (libpq) incluida, en Linux, macOS y Windows, según su README. Solo si se compila desde el código fuente necesitas las cabeceras de libpq (en Debian y Ubuntu, el paquete libpq-dev).
Usuario, host y contraseña con variables de entorno
Si tu PostgreSQL está en otra máquina, en un contenedor o pide contraseña (lo normal), añade la conexión al bloque default, leyendo cada dato de una variable de entorno:
default: &default
adapter: postgresql
encoding: unicode
max_connections: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
host: <%= ENV.fetch("DB_HOST") { "localhost" } %>
username: <%= ENV.fetch("DB_USERNAME") { "postgres" } %>
password: <%= ENV["DB_PASSWORD"] %>
Los nombres DB_HOST, DB_USERNAME y DB_PASSWORD son una convención de este ejemplo: Rails no les da un significado especial, solo lee lo que pongas en el ERB. Así el fichero se puede subir al repositorio sin ningún secreto dentro, y cada persona o servidor define sus propias variables:
export DB_PASSWORD='tu-contraseña'
Crear la base de datos y aplicar las migraciones
bin/rails db:create
Created database 'tienda_development'
Created database 'tienda_test'
En desarrollo, db:create crea también la base de datos de test. Ahora un modelo de ejemplo y su migración:
bin/rails generate model Producto nombre:string precio:decimal
bin/rails db:migrate
invoke active_record
create db/migrate/20261109010105_create_productos.rb
create app/models/producto.rb
== 20261109010105 CreateProductos: migrating ==================================
-- create_table(:productos)
-> 0.0043s
== 20261109010105 CreateProductos: migrated (0.0043s) =========================
Para comprobar que Rails está hablando de verdad con PostgreSQL, guarda un registro y pregunta a la conexión:
bin/rails runner 'Producto.create!(nombre: "Taza", precio: 7.5); p Producto.count; p ActiveRecord::Base.connection.adapter_name; p ActiveRecord::Base.connection.select_value("select version()")'
1
"PostgreSQL"
"PostgreSQL 18.6 (Debian 18.6-1.pgdg13+2) on x86_64-pc-linux-gnu, compiled by gcc (Debian 14.2.0-19) 14.2.0, 64-bit"
Si quieres entender qué hace cada migración y cómo deshacerla, lo tienes en migraciones en Ruby on Rails.
Cambiar de SQLite a PostgreSQL
Si el proyecto ya existe y usa SQLite, Rails hace el cambio con un comando:
bin/rails db:system:change --to=postgresql
conflict config/database.yml
Overwrite /root/tienda/config/database.yml? (enter "h" for help) [Ynaqdhm]
force config/database.yml
gsub Gemfile
gsub Gemfile
gsub Dockerfile
gsub Dockerfile
Te pregunta antes de sobrescribir config/database.yml (responde Y; la ruta será la de tu proyecto) y deja el fichero con la misma plantilla de PostgreSQL que verías en un proyecto nuevo. También cambia gem "sqlite3" por gem "pg", "~> 1.1" en el Gemfile y adapta el Dockerfile que genera Rails: cambia el paquete sqlite3 por postgresql-client y añade libpq-dev para compilar. Después:
- Instala la gema nueva con
bundle install. - Añade
host,usernameypasswordcon variables de entorno, como en el apartado anterior, si tu servidor lo necesita. - Crea la base de datos y aplica las migraciones:
bin/rails db:create db:migrate.
Los datos que tuvieras en SQLite no se copian: el comando cambia la configuración, no mueve los datos. Si necesitas conservarlos, tendrás que exportarlos e importarlos con una herramienta aparte o con un script propio.
El mismo comando sirve para MySQL, con --to=mysql o --to=trilogy.
DATABASE_URL: toda la conexión en una variable
En lugar de repartir la conexión en varias claves, puedes darla entera en una URL dentro de la variable de entorno DATABASE_URL. Es la forma habitual en muchos servicios de alojamiento, que te dan esa URL ya preparada:
export DATABASE_URL="postgres://postgres:tu-contraseña@localhost:5432/tienda_development"
La guía oficial explica cómo se combina con config/database.yml:
- Si solo existe
DATABASE_URL, Rails se conecta con ella. - Si existen las dos, Rails las mezcla: los datos que solo están en el fichero (por ejemplo,
max_connections) se mantienen, y si un dato aparece en los dos sitios, gana la variable de entorno. - Si un entorno del fichero tiene su propia clave
url,DATABASE_URLse ignora para ese entorno.
En la prueba, con DATABASE_URL apuntando al servidor db (el nombre del contenedor de PostgreSQL), esta es la conexión que usó Rails:
bin/rails runner 'p ActiveRecord::Base.connection_db_config.configuration_hash.slice(:adapter, :host, :database)'
{adapter: "postgresql", host: "db", database: "tienda_development"}
Para que se vea a simple vista que producción depende solo de la variable, la guía recomienda escribirlo así:
production:
url: <%= ENV["DATABASE_URL"] %>
DATABASE_URL se aplica al entorno con el que arrancas Rails. En la prueba, bin/rails db:create con la variable definida creó solo tienda_development, sin la base de datos de test que crea cuando lee únicamente el fichero.
MySQL en Rails
El paso a MySQL sigue el mismo camino que el de PostgreSQL, con su adaptador:
| Base de datos | Proyecto nuevo | Proyecto existente |
|---|---|---|
| PostgreSQL | rails new tienda -d postgresql |
bin/rails db:system:change --to=postgresql |
MySQL con mysql2 |
rails new tienda -d mysql |
bin/rails db:system:change --to=mysql |
MySQL con trilogy (no necesita librería del sistema) |
rails new tienda -d trilogy |
bin/rails db:system:change --to=trilogy |
| SQLite | rails new tienda |
— |
Con la gema mysql2 sí necesitas instalar antes las cabeceras de la librería cliente de MySQL. Su README da varios nombres posibles del paquete, según la distribución (libmysqlclient-dev, default-libmysqlclient-dev, libmariadb-dev o mysql-devel). En Ubuntu, por ejemplo:
sudo apt install libmysqlclient-dev
En el artículo original, de 2018, la gema se añadía a mano al Gemfile; hoy lo hace db:system:change. Este es el principio de aquel Gemfile, con la línea añadida debajo de sqlite3:
source 'https://rubygems.org'
git_source(:github) { |repo| "https://github.com/#{repo}.git" }
ruby '2.5.1'
# Bundle edge Rails instead: gem 'rails', github: 'rails/rails'
gem 'rails', '~> 5.2.0'
# Use sqlite3 as the database for Active Record
gem 'sqlite3'
gem "mysql2"
# Use Puma as the app server
gem 'puma', '~> 3.11'
Así quedaba el bloque de desarrollo en aquella versión:
default: &default
adapter: sqlite3
pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
timeout: 5000
development:
adapter: mysql2
username: root
password:
host: 127.0.0.1
port: 3306
database: prueba
pool: 5
timeout: 5000
# Warning: The database defined as "test" will be erased and
# re-generated from your development database when you run "rake".
# Do not set this db to the same as development or production.
test:
<<: *default
database: db/test.sqlite3
production:
<<: *default
database: db/production.sqlite3
Y esta es la parte principal de lo que genera Rails 8.1 con --to=mysql:
default: &default
adapter: mysql2
encoding: utf8mb4
max_connections: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
username: root
password:
host: <%= ENV.fetch("DB_HOST") { "127.0.0.1" } %>
development:
<<: *default
database: tienda_development
test:
<<: *default
database: tienda_test
Igual que con PostgreSQL, la contraseña de producción sale de una variable de entorno (password: <%= ENV["TIENDA_DATABASE_PASSWORD"] %>), y en desarrollo puedes leer la tuya con <%= ENV["DB_PASSWORD"] %>. La configuración de MySQL de este apartado se ha generado con Rails 8.1.4.1, en un proyecto tienda, pero no se ha probado contra un servidor MySQL real. Para ver las tablas desde la terminal, mira cómo conectarte a MySQL desde la consola.
Errores típicos al configurar la base de datos
connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed: No such file or directory. Rails ha intentado conectar por el socket local porque en database.yml no hay host, y no hay ningún PostgreSQL escuchando en tu máquina. Es lo que pasa con la plantilla generada si tu servidor está en Docker o en otra máquina. Añade host (o usa DATABASE_URL) y comprueba que el servidor está arrancado.
connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed: No such file or directory
Is the server running locally and accepting connections on that socket?
password authentication failed for user "postgres". El servidor responde, pero el usuario o la contraseña no coinciden. Revisa qué valor tiene la variable de entorno en la terminal donde lanzas Rails (echo $DB_PASSWORD): si abriste otra terminal, puede que no esté definida.
connection to server at "172.20.0.2", port 5432 failed: FATAL: password authentication failed for user "postgres"
Couldn't create 'tienda_development' database. Please check your configuration.
bin/rails aborted!
Could not find gem 'pg (~> 1.1)' in locally installed gems. (Bundler::GemNotFound). Has cambiado de base de datos con db:system:change, pero no has ejecutado bundle install. Instálala y vuelve a lanzar el comando.
Database 'tienda_development' already exists. No es un error: db:create avisa de que ya estaba creada y sigue adelante.
La contraseña en el repositorio. No da ningún mensaje, y por eso se cuela con facilidad. Si escribes la contraseña en claro en database.yml y haces commit, queda en el historial aunque luego la borres. Léela siempre de una variable de entorno.
Qué base de datos elegir
Un resumen orientativo, que es explicación nuestra a partir de la guía oficial:
| SQLite | PostgreSQL | MySQL / MariaDB | |
|---|---|---|---|
| Servidor aparte | No, es un fichero | Sí | Sí |
| Configuración | Ninguna | Host, usuario y contraseña | Host, usuario y contraseña |
| Para empezar a aprender | Ideal | Bien | Bien |
| Producción con mucho tráfico | La guía avisa de que puede desbordarse | Sí | Sí |
Si estás aprendiendo, empieza con SQLite y no pierdas tiempo instalando servidores. Si tu proyecto va a desplegarse en un servicio que te da una base de datos gestionada, usa la misma en desarrollo: que tu ordenador se parezca a producción evita sorpresas.
Si todavía no tienes el proyecto creado, empieza por crear y arrancar un nuevo proyecto en Ruby on Rails. Con la base de datos lista, el siguiente paso son los modelos y las migraciones.
Fuentes
- Guía oficial de Rails 8.1.4.1, Configuring Rails Applications:
database.yml,DATABASE_URLy cómo se combinan, SQLite, PostgreSQL y MySQL. Consultada el 9 de noviembre de 2026. - README de la gema pg (versión 1.7.0): gemas binarias con libpq incluida. Consultado el 9 de noviembre de 2026.
- README de mysql2 (versión 0.5.7): paquetes del sistema necesarios. Consultado el 9 de noviembre de 2026.
- Imagen oficial de PostgreSQL en Docker Hub: la variable
POSTGRES_PASSWORDy el usuariopostgresse han comprobado al ejecutarla.
Cómo se ha probado. El 9 de noviembre de 2026, con Docker: la imagen oficial ruby:latest (Ruby 4.0.9) y Rails 8.1.4.1, contra la imagen oficial postgres (PostgreSQL 18.6), en una red de Docker temporal que se borró al terminar. Se han ejecutado rails new con SQLite y con -d postgresql, bin/rails db:system:change --to=postgresql, bin/rails db:create db:migrate, bin/rails runner y DATABASE_URL, y se han provocado los errores de la sección anterior. Las salidas de este artículo son las de esa prueba. La parte de MySQL se generó con Rails 8.1.4.1 y Ruby 4.0.9, pero no se ha ejecutado contra un servidor MySQL. Las capturas son de la versión original, con Rails 5.2.