DbToolsBundle

DbToolsBundle is a PHP tool designed to simplify frequent database-related tasks for developers. Its core capabilities include:

• Backup: Creating copies of your databases.
• Restore: Restoring databases from backups.
• Anonymize: Protecting sensitive data by anonymizing database contents.

For DevOps workflows, a Docker image is available to run these tools in containerized environments.

DbToolsBundle is a PHP tool designed for managing database lifecycles. Key capabilities include:

• Back up: Back up your database and manage dumps via CLI commands.
• Restore: Restore previous database dumps easily.
• Anonymize: Configure database anonymization using YAML files.
• GDPR-friendly workflows: Facilitate GDPR best practices when importing production dumps into non-production environments.
• Symfony Integration: Provides autoconfiguration and allows for anonymization using PHP attributes on Doctrine Entities.

DbToolsBundle is available in four distinct flavors depending on your environment and framework requirements:

1. Standalone: A pure PHP library usable in any Composer-managed project. Access the binary via vendor/bin/db-tools.
2. Symfony: A dedicated bundle that integrates deeply with Symfony. It provides autoconfigured database connections via DBAL, Symfony Console commands, and attribute-based anonymization on Doctrine Entities.
3. Docker: A containerized version based on FrankenPHP, ideal for CI/CD pipelines. Commands are executed via docker container run.
4. Laravel (experimental): An integration for Laravel projects that provides Artisan commands and autoconfigured connections via the Illuminate database manager.

DbToolsBundle uses a decentralized approach where the core bundle remains lightweight. If the core anonymizers do not meet your needs, you can:

1. Search for official packs: Check the DbToolsBundle/packs-status repository for the status of official packs.
2. Search GitHub: Look for community-contributed packs using the topic db-tools-bundle-pack.
3. Create custom anonymizers: If no existing pack fits, you can implement your own custom anonymizers and share them with the community.

The password anonymizer allows you to set the same plain-text password for every user in your database. It uses the Symfony PasswordHasher Component to hash the provided plain password before storage.

Configuration Options

When configuring the password anonymizer, you can provide the following options:

• algorithm: The hashing algorithm to use (e.g., 'sodium'). The default is 'auto'.
• password: The plain-text password that will be set for every row. The default is 'password'.

Unlike traditional PHP anonymization tools that follow a three-step process (Load data $\rightarrow$ Anonymize in PHP $\rightarrow$ Persist to DB), DbToolsBundle anonymizes directly with SQL queries.

By leveraging the database management system (DBMS) to process data, the bundle avoids the overhead of pulling large datasets into PHP memory. The bundle generates optimized, complex update queries tailored specifically for the target database platform (SQLite, PostgreSQL, MariaDB, or MySQL) to ensure maximum efficiency.

The configuration structure depends on how you are running the toolset.

• Symfony Bundle: You must wrap all configuration under a top-level db_tools key to avoid conflicts with other bundles.
• Standalone Console / Docker: You must omit the db_tools top-level section and place configuration keys at the root of the file.

Note on Paths:

• In Symfony, use absolute paths (e.g., using %kernel.project_dir%).
• In Standalone/Docker, relative paths are relative to the directory of the configuration file itself, unless a workdir is provided.

Most configuration options in DbToolsBundle can be defined at two levels:

1. Top-level: Applies the setting to all connections.
2. Connection-level: Applies the setting only to a specific connection defined under the connections key.

When working with multiple connections, any connection that does not explicitly specify an option will inherit the value from the top-level default configuration.

# Example of top-level vs connection-level configuration
db_tools:
    # Top-level default
    backup_excluded_tables: ['table1']
    connections:
        connection_one:
            # Overrides top-level
            backup_excluded_tables: ['table2']
        connection_two:
            # Inherits ['table1'] from top-level
            pass: true

You can inject a value from another anonymizer into a pattern by using the syntax {ANONYMIZER}. The placeholder will be replaced by a random value produced by that specific anonymizer.

Warning: The target anonymizer must not be a multi-column anonymizer.

"My email address is {email}, what's yours?"

Backups are stored in a directory that can be configured. The default locations are:

• Standalone: ./var/db_tools (relative to the yaml config file)
• Symfony: %kernel.project_dir%/var/db_tools
• Docker: /var/www/var/db_tools (inside the container)

Files are organized into sub-directories by date. The filename format is {connection_name}-{date}{timestamp}.{extension}.

Example for a backup of the default connection made on 2023-05-15 at 12:22:35:

• Symfony path: %kernel.project_dir%/var/db_tools/2023/05/default-20230515122235.sql