Nivel inicial12 min de lectura · Publicado el

Configurar la BBDD en Ruby on Rails: database.yml

database.yml en Rails: el bloque default guarda lo común y development, test y production lo reutilizan con <<: *default. Lo común va en defaultrubentejera.com &default<<: *defaultdevelopmenttestproductionENV["…_PASSWORD"]
El bloque default reúne lo común (adapter, encoding, username) y cada entorno lo copia con <<: *default y solo añade lo suyo, como el nombre de la base de datos. En producción, la contraseña sale de una variable de entorno.

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:

  1. Instala la gema nueva con bundle install.
  2. Añade host, username y password con variables de entorno, como en el apartado anterior, si tu servidor lo necesita.
  3. 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_URL se 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

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.