Propósito

Tener a mano los comandos de Docker y Docker Compose que más se usan en el día a día de un proyecto, y el procedimiento para exportar e importar la base de datos de un contenedor, sea para pasarla a un compañero o para respaldarla.

Los ejemplos usan el proyecto Racafé (Wagtail + PostgreSQL 16), cuyo docker-compose.yml define dos servicios: db (postgres, usuario/base racafe) y web (Django). En otro proyecto, cambia el nombre del servicio, el usuario y la base por los de su docker-compose.yml.

Explicación

1. Levantar, ver y detener

2. Ejecutar comandos dentro de un contenedor

Comandos de Django habituales en este proyecto:

docker compose run --rm web python manage.py check
docker compose run --rm web python manage.py makemigrations --check --dry-run
docker compose run --rm web python manage.py migrate
docker compose run --rm web python manage.py createsuperuser
docker compose run --rm web pytest

3. Imágenes, volúmenes y limpieza

4. Exportar la base de datos (PostgreSQL)

Con los contenedores arriba (docker compose up -d), desde la raíz del proyecto:

docker compose exec -T db pg_dump -U racafe -Fc racafe > racafe.dump
tar czf racafe-media.tgz media

• -Fc genera el formato comprimido de PostgreSQL, el que entiende pg_restore.
• -T es obligatoria: sin ella Docker asigna una terminal y corrompe el archivo binario.
• La carpeta media/ guarda las imágenes y documentos subidos al CMS. La base sola deja las imágenes rotas; por eso viajan las dos.
• Si prefieres un SQL legible: docker compose exec -T db pg_dump -U racafe racafe > racafe.sql.

5. Importar la base de datos (PostgreSQL)

Copia racafe.dump y racafe-media.tgz a la raíz del proyecto y corre:

docker compose up -d db
docker compose stop web
docker compose exec -T db pg_restore -U racafe -d racafe 
    --clean --if-exists --no-owner < racafe.dump
tar xzf racafe-media.tgz
docker compose up -d
docker compose exec web python manage.py migrate

• --clean --if-exists borra las tablas existentes antes de recrearlas: reemplaza por completo la base local. Si tienes algo que conservar, exporta primero tu propia base.
• Se detiene web para que no haya conexiones abiertas mientras se restaura.
• El migrate final aplica las migraciones que tu rama tenga y el dump no.
• Los usuarios del CMS viajan en el dump: entras con las credenciales de quien lo sacó, o creas las tuyas con createsuperuser.
• Si el archivo es .sql (texto plano): docker compose exec -T db psql -U racafe racafe < racafe.sql.

6. Lo mismo en MySQL / MariaDB

Si el servicio de base es MySQL o MariaDB (cambia db, usuario, contraseña y base por los del proyecto):

# Exportar
docker compose exec -T db mysqldump -u USUARIO -pCLAVE BASE > base.sql
# Importar
docker compose exec -T db mysql -u USUARIO -pCLAVE BASE < base.sql

En imágenes recientes de MariaDB los binarios se llaman mariadb-dump y mariadb.

Ejemplo

Correcto: docker compose exec -T db pg_dump -U racafe -Fc racafe > racafe.dump → archivo binario válido que pg_restore acepta.

Incorrecto: docker compose exec db pg_dump -U racafe -Fc racafe > racafe.dump (sin -T) → pg_restore falla con «input file does not appear to be a valid archive».

Incorrecto: docker compose down -v para «reiniciar» → la -v borra los volúmenes y con ellos toda la base de datos. Úsalo solo si de verdad quieres empezar de cero y ya tienes un dump.

Excepciones

• Datos personales: el dump incluye los leads de los formularios. Compártelo por un canal privado y nunca lo subas al repositorio (el .gitignore debe excluir *.dump, *.sql y *.tgz).
• Proyectos WordPress con DDEV no usan estos comandos: van con ddev export-db / ddev import-db.
• En Docker Compose v1 el comando es docker-compose (con guion); en la v2 es docker compose.