DDEV MTK

Overview

This add-on integrates MySQL Toolkit into your DDEV project. You want this add-on if your site's database is large, and its getting slow to copy it for local development, or CI testing, or preview environments (e.g. TugBoat).

DDEV's typical approach for pulling down the database from Production is to copy a database dump and re-import locally. The re-import can be a slow process, even when MySQL is well tuned. MTK imports the database once into a Docker image, so your developers and CI just have to fetch an image and they are off and running. No re-import required. Docker images are already compressed, so the fetch is relatively quick.

Note that the MTK approach can make site setup fast enough for functional tests using existing site data. See Drupal Test Traits for a project that facilitates this.

Installation

Note

Installation will not interfere with your current site.

ddev add-on get weitzman/ddev-mtk
ddev restart
ddev describe

Notice that you now have an mtk service listed in ddev describe. At first, this is an empty and unused placeholder MySQL database image. Read on to learn how you build and publish your site's database image, which will replace the placeholder image.

Run ddev exec mtk table list db. You should see a list of table names. This verifies that mtk is installed in the web service.

Configuration

1. Create a mtk.yml file in the root of your project. It can be empty to start. Eventually, populate it as per https://mtk.skpr.io/docs/tutorial#configuration-file, for a slimmed and sanitized database.
2. Run ddev exec mtk dump db > dump.sql to generate a SQL dump file.
3. Use the dump.sql from above when building and pushing your database image to a Docker registry (e.g. Docker Hub). See the tutorial at https://mtk.skpr.io/docs/database-image. Do this on the host, not in the container. Remember to push to a private Docker repository.
4. Now that you have published a DB image with your data inside, configure your site to use it.
5. Edit .ddev/.env.mtk.web as follows:
   • Remove the #ddev-generated line at the top.
   • Set MTK_HOSTNAME=mtk
   • Edit MTK_USER, MTK_PASSWORD, MTK_DATABASE to match whatever your published expects.
   • Set DDEV_MTK_DOCKER_IMAGE to the image and tag that you published above. For example, example/db:latest
6. Edit Drupal's settings.php with code like below so that Drupal connects to the mtk service instead of the typical db service.

   if (getenv('IS_DDEV_PROJECT') == 'true') {
   $file_mtk = getenv('DDEV_COMPOSER_ROOT') . '/.ddev/settings.ddev-mtk.php';
   if (file_exists($file_mtk)) {
     include $file_mtk;
    }
   }

7. ddev restart. Your site is now using the mtk service instead of db. Make sure the site works by running ddev drush st (look for Drupal bootstrap: Successful). Run ddev launch and to verify that a browser request succeeds.
8. Optional. Omit the standard db service since your site no longer uses it. ddev config --omit-containers db
9. Commit the .ddev directory and settings.php change to version control so your teammates start using the mtk service.
10. Set up a CI job to refresh your database image on a weekly or nightly basis. The job should push to the same tag every time (e.g. latest).

CI, Preview Environments, and more.

Consider speeding up other DB consumers by using the image you published above. See https://mtk.skpr.io/docs/database-image#integrate-with-your-cicd-pipeline for a few helpful snippets. Consider using own runners such as (Bitbucket, Gitlab CI to highly isolate your DB data.

Commands

Command	Description
ddev exec mtk	List tables, sanitize tables, dump a database.
ddev pulldb	Refresh your site's database (i.e. the mtk Docker image)
ddev sequelace	Open your site's DB in the Sequel Ace GUI application
ddev tableplus	Open your site's DB in the TablePlus GUI application

Limitations

• Non-functional DDEV commands:
  • export-db, import-db. Use Drush sql commands instead.
  • snapshot. Not usually needed since you can revert your Docker image.

Credits

Contributed and maintained by @weitzman