From b26e9ce898a4a99ffbe62ef07e927c9e6f2fcaa1 Mon Sep 17 00:00:00 2001 From: Pierre Rineau Date: Fri, 22 Nov 2024 10:22:12 +0100 Subject: [PATCH] issue #194 - configuration basics documentation --- docs/.vitepress/config.ts | 2 +- .../anonymization/custom-anonymizers.md | 2 +- docs/content/anonymization/essentials.md | 12 +- docs/content/backup_restore.md | 22 +- docs/content/configuration.md | 329 --------- docs/content/configuration/basics.md | 657 ++++++++++++++++++ docs/content/configuration/reference.md | 567 ++++++++------- docs/content/contribute/pack.md | 4 +- docs/content/getting-started/basics.md | 7 +- docs/content/getting-started/flavors.md | 2 +- docs/content/getting-started/installation.md | 4 +- 11 files changed, 1016 insertions(+), 592 deletions(-) delete mode 100644 docs/content/configuration.md create mode 100644 docs/content/configuration/basics.md diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index e975c83b..600553b8 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -85,7 +85,7 @@ export default defineConfig({ items: [ { text: 'Backup & Restore', link: '/backup_restore' }, { text: 'Statistics', link: '/stats' }, - { text: 'Bundle configuration', link: '/configuration' }, + { text: 'Configuration basics', link: '/configuration/basics' }, { text: 'Configuration reference', link: '/configuration/reference' }, ] }, diff --git a/docs/content/anonymization/custom-anonymizers.md b/docs/content/anonymization/custom-anonymizers.md index bfcb9b0d..a91e58f8 100644 --- a/docs/content/anonymization/custom-anonymizers.md +++ b/docs/content/anonymization/custom-anonymizers.md @@ -35,7 +35,7 @@ To inspire you, browse existing *Anonymizers* in `vendor/makinacorpus/db-tools-b ::: tip You can tell *DbToolsBundle* your *Custom Anonymizers* live in a different directory -with the [*Anonymizer paths* configuration](../configuration#anonymizer-paths). +with the [*Anonymizer paths* configuration](../configuration/basics#anonymizer-paths). ::: ::: tip diff --git a/docs/content/anonymization/essentials.md b/docs/content/anonymization/essentials.md index 96e3ccee..8c0e9d4f 100644 --- a/docs/content/anonymization/essentials.md +++ b/docs/content/anonymization/essentials.md @@ -13,15 +13,15 @@ With the Symfony bundle, there is two ways to tell *DbToolsBundle* how it should 2. you can declare it with a **YAML** file ::: tip -The *DbToolsBundle* does not only work with Doctrine Entities to anonymize data. You can use it with +*DbToolsBundle* does not only work with Doctrine Entities to anonymize data. You can use it with *any* database, all you need is a DBAL connection. -In such case, the [YAML configuration](../configuration#anonymization) is the only available option. +In such case, the [YAML configuration](../configuration/basics#anonymization) is the only available option. ::: -If Doctrine ORM is enabled, the *DbToolsBundle* will automatically look for attributes on your entities. +If Doctrine ORM is enabled, *DbToolsBundle* will automatically look for attributes on your entities. If you want to use YAML configuration, look at the [Bundle Configuration -section](../configuration#anonymization) to see how to configure it. +section](../configuration/basics#anonymization) to see how to configure it. :::info All anonymizers can be configured via attributes on Doctrine ORM entities, but inheritance @@ -225,7 +225,7 @@ customer: ## Going further -The DbToolsBundle provides a bunch of *Anonymizers* that should cover most of your needs. You can find a +*DbToolsBundle* provides a bunch of *Anonymizers* that should cover most of your needs. You can find a complete description of each one of them in the next section. You can also add *Anonymizers* from [community packs](./packs). For example, to add the `pack-fr-fr` run: @@ -234,7 +234,7 @@ You can also add *Anonymizers* from [community packs](./packs). For example, to composer require db-tools-bundle/pack-fr-fr ``` -If you can't find what you need from core anonymizers and in available packs, the *DbToolsBundle* allows +If you can't find what you need from core anonymizers and in available packs, *DbToolsBundle* allows you to [create your own *Custom Anonymizers*](./custom-anonymizers). ::: tip diff --git a/docs/content/backup_restore.md b/docs/content/backup_restore.md index fa0ad28d..4f931466 100644 --- a/docs/content/backup_restore.md +++ b/docs/content/backup_restore.md @@ -5,13 +5,13 @@ your database but also a tiny backups manager which handle backup files for you. ## Backup command -The backup command will use the [predefined or configured binary](./configuration#binaries) for your +The backup command will use the [predefined or configured binary](./configuration/basics#binaries) for your database vendor with correct parameters to dump your database. -Each time you launch the backup command, [a backup file is stored in a directory](./configuration#storage-directory) (See +Each time you launch the backup command, [a backup file is stored in a directory](./configuration/basics#storage-directory) (See [Storage section](#storage) below for more information on how backup files are stored). -With time, this directory will grow, that's why a [backup expiration age](./configuration#storage-directory#backup-expiration-age) +With time, this directory will grow, that's why a [backup expiration age](./configuration/basics#storage-directory#backup-expiration-age) was added. Every time you launch the command, at the end, it will be asked if you want to remove obsolete backup files (i.e. files that have passed their expiration date). @@ -60,7 +60,7 @@ php bin/console db-tools:backup --connection other_connection_name ### Excluded tables -You may have configured [tables to be exclude in the bundle configuration](./configuration#excluded-tables). +You may have configured [tables to be exclude in the bundle configuration](./configuration/basics#excluded-tables). If so, these tables will be automatically excluded each time you launch the command. But if you want to temporarily exclude some tables, run the command with the `--excluded-table` option: @@ -132,11 +132,11 @@ php bin/console db-tools:backup --extra-options "--opt1 val1 --opt2 val2 --flag" Unless you specify the `--ignore-default-options` option, the custom options -will be added to the [default options](./configuration#default-binary-options). +will be added to the [default options](./configuration/basics#default-binary-options). ### Ignoring default options -If necessary, [default options](./configuration#default-binary-options) can be +If necessary, [default options](./configuration/basics#default-binary-options) can be ignored for a backup by using the `--ignore-default-options` option:
@@ -158,7 +158,7 @@ php bin/console db-tools:backup --ignore-default-options ## Restore command -The restore command will use [predefined or configured binary](./configuration#binaries) for your database vendor with correct parameters +The restore command will use [predefined or configured binary](./configuration/basics#binaries) for your database vendor with correct parameters to restore your database from an existing backup files.
@@ -280,11 +280,11 @@ php bin/console db-tools:restore --extra-options "--opt1 val1 --opt2 val2 --flag
Unless you specify the `--ignore-default-options` option, the custom options -will be added to the [default options](./configuration#default-binary-options). +will be added to the [default options](./configuration/basics#default-binary-options). ### Ignoring default options -If necessary, [default options](./configuration#default-binary-options) can be +If necessary, [default options](./configuration/basics#default-binary-options) can be ignored for a restoration by using the `--ignore-default-options` option:
@@ -307,11 +307,11 @@ php bin/console db-tools:restore --ignore-default-options ## Storage -As mentioned earlier on this page, the *DbToolsBundle* can list existing backup files +As mentioned earlier on this page, *DbToolsBundle* can list existing backup files when you want to restore a previous one with the restore command. All backups are stored in a directory. By default this directory is `./var/db_tools` (relative to the yaml config file)`%kernel.project_dir%/var/db_tools` -but [you can choose the directory you want](./configuration#storage-directory). +but [you can choose the directory you want](./configuration/basics#storage-directory). In this directory, each backup is put in sub-directories depending on the backup date. The backup's filename is generated from the backup date and the DBAL connection name of the database. diff --git a/docs/content/configuration.md b/docs/content/configuration.md deleted file mode 100644 index ff8e0768..00000000 --- a/docs/content/configuration.md +++ /dev/null @@ -1,329 +0,0 @@ -# Bundle configuration - -The *DbToolsBundle* let you configure some of its behaviors. As with any classic Symfony Bundle, -all will take place in the `config/packages/db_tools.yaml` file. - -:::tip -A complete example of this file can be found in the bundle sources in: `vendor/makinacorpus/db-tools-bundle/config/packages/db_tools.yaml` -::: - -For detailed information about configuration options, please see the -[configuration reference](configuration/reference). - -## Backup configuration - -Some options are available to customize how the `db-tools:backup` command works. - -### Storage - -#### Root directory - -The `db_tools.storage.root_dir` parameter let you choose where to put the generated dumps. - -Default value is `'%kernel.project_dir%/var/db_tools'`. - -#### File and directory naming strategy - -Default behavior will store your backup using this strategy: -`%db_tools.storage.root_dir%///-.` -where `` is the file extension depending upon the database backend (mostly `.sql` or `.dump`). - -Custom strategy can be implemented by extending the -`MakinaCorpus\DbToolsBundle\Storage\AbstractFilenameStrategy` abstract class: - -```php -namespace App\DbTools\Storage; - -use MakinaCorpus\DbToolsBundle\Storage\AbstractFilenameStrategy; - -class FooFilenameStrategy extends AbstractFilenameStrategy -{ - #[\Override] - public function generateFilename( - string $connectionName = 'default', - string $extension = 'sql', - bool $anonymized = false - ): string { - return '/some_folder/' . $connectionName . '.' . $extension; - } -} -``` - -Then registered this way, on a per-connection basis: - -```yaml -# config/packages/db_tools.yaml - -db_tools: - storage: - filename_strategy: - connection_name: App\DbTools\Storage\FooFilenameStrategy -``` - -Value can be a container service identifier, or directly a class name in case this -has no constructor arguments. - -If you need to store your dumps outside of the `%db_tools.storage.root_dir%` directory, -then implement the `MakinaCorpus\DbToolsBundle\Storage\FilenameStrategyInterface` directly -and add the following method: - -```php -namespace App\DbTools\Storage; - -use MakinaCorpus\DbToolsBundle\Storage\FilenameStrategyInterface; - -class FooFilenameStrategy implements FilenameStrategyInterface -{ - #[\Override] - public function generateFilename(/* ... */): string {} - - #[\Override] - public function getRootDir( - string $defaultRootDir, - string $connectionName = 'default', - ): string { - return '/some/path/' . $connectionName . '/foo'; - } -} -``` - -This will allow the restore command to find your backups. - -### Excluded tables - -The `excluded_tables` parameter let you configure tables to exclude from backups. You will need to give a -configuration per doctrine connection. - -Default value is `null`: no table are excluded. - -Here is an example for exclude `table1` and `table2` for the `default` doctrine connection: - -```yml -# config/packages/db_tools.yaml - -db_tools: - - #... - - excluded_tables: - default: ['table1', 'table2'] - - #... -``` - -:::tip -Note that you can override this configuration while running the `db-tools:backup` command using -the `--exclude` option. -::: - -### Binary options - -See the [default binary options](#default-binary-options) section. - -### Backup expiration age - -The `backup_expiration_age` parameter let you choose when a backup is considered as obsolete. - -Default value is `'3 months ago'`. - -Use [PHP relative date/time formats](https://www.php.net/manual/en/datetime.formats.relative.php) -for this value. - -```yml -# config/packages/db_tools.yaml - -db_tools: - - #... - - backup_expiration_age: '1 week ago' - - #... -``` - -### Backup and restore timeout - -The `backup_timeout` and `restore_timeout` options let you choose what is the backup and restore -processes timeout in seconds. - -Default value is `600` (seconds) for backup, `1800` (seconds) for restore. - -Value can be either a [\DateInterval::createFromDateString()](https://www.php.net/manual/en/dateinterval.createfromdatestring.php) -compatible string value or a number of seconds as an integer value. - -```yml -# config/packages/db_tools.yaml - -db_tools: - - #... - - # As a date interval string. - backup_timeout: '6 minutes 30 seconds' - restore_timeout: '3 minutes 15 seconds' - - # As a number of seconds integer value. - backup_timeout: 390 - restore_timeout: 195 - - #... -``` - -## Binaries - -`db-tools:backup` and `db-tools:restore` need your system/environment to provide some extra binaries -to be able to work. These binaries depend on the database vendor you use, you will need: -* for MariaDB: `mariadb-dump` and `mariadb` -* for MySQL: `mysqldump` and `mysql` -* for PostgreSQL: `pg_dump` and `pg_restore` -* for SQLite: `sqlite3` - -You can verify if those binaries are well found by the *DbToolsBundle*, -for each of your DBAL connections, by launching: - -```sh -php bin/console db-tools:check -``` - -If the `db-tools:check` command returns you some errors: - * if your binaries are present on your system but the *DbToolsBundle* can't find them: you will need - to specify path for these binaries: - - ```yml - # config/packages/db_tools.yaml - - db_tools: - - #... - - # Specify here paths to binaries, only if the system can't find them by himself - # platform are 'mysql', 'postgresql', 'sqlite' - backupper_binaries: - mariadb: '/usr/bin/mariadb-dump' # default 'mariadb-dump' - mysql: '/usr/bin/mysqldump' # default 'mysqldump' - postgresql: '/usr/bin/pg_dump' # default 'pg_dump' - sqlite: '/usr/bin/sqlite3' # default 'sqlite3' - restorer_binaries: - mariadb: '/usr/bin/mariadb' # default 'mariadb' - mysql: '/usr/bin/mysql' # default 'mysql' - postgresql: '/usr/bin/pg_restore' # default 'pg_restore' - sqlite: '/usr/bin/sqlite3' # default 'sqlite3' - - #... - ``` - * Or, if your binaries are not present on your system: you will need to install them - - - -:::tip -If your app lives in the [official PHP docker image](https://hub.docker.com/_/php/), -you can install correct binaries adding these lines to your Dockerfile, - -for PostgreSQL: - -``` -RUN apt-get update && \ - apt-get install -y --no-install-recommends postgresql-client -``` - -for MariaDB/MySQL: - -``` -RUN apt-get update && \ - apt-get install -y --no-install-recommends default-mysql-client -``` -::: - -:::warning -Dump and restore is not supported yet for SQL Server. -::: - -### Default binary options - -Apart from the essential options (credentials, database name, etc.), the bundle -also passes a few default options to the binary depending on the operation being -performed and the invoked binary itself. You can customize those default options -by configuring your own ones per operation type and DBAL connection: - -```yaml -# config/packages/db_tools.yaml -db_tools: - # ... - - backupper_options: - default: '--an-option' - another_connection: '-xyz --another' - restorer_options: - default: '--a-first-one --a-second-one' - another_connection: '-O sample-value' -``` - -If you do not define your own default options, the following ones will be used -according to the database vendor: - -* When backing up: - * MariaDB: `--no-tablespaces` - * MySQL: `--no-tablespaces` - * PostgreSQL: `-Z 5 --lock-wait-timeout=120` - * SQLite: `-bail` -* When restoring: - * MariaDB: None - * MySQL: None - * PostgreSQL: `-j 2 --clean --if-exists --disable-triggers` - * SQLite: None - -## Anonymizer paths - -By default, the *DbToolsBundle* will look for *anonymizers* in 2 directories - -* `%kernel.project_dir%/vendor/makinacorpus/db-tools-bundle/src/Anonymizer` -* `%kernel.project_dir%/src/Anonymizer` - -If you want to put custom anonymizers in another directory or if you want to load -a pack of anonymizers from an external library, you can modify/add paths: - - -```yml -# config/packages/db_tools.yaml - -db_tools: - # ... - - anonymizer_paths: - - '%kernel.project_dir%/vendor/makinacorpus/db-tools-bundle/src/Anonymization/Anonymizer' - - '%kernel.project_dir%/src/Anonymizer' - - '%kernel.project_dir%/vendor/myAnonymizerProvider/anonymizers/src' - - # ... -``` - -## Anonymization - -Per default, the **DbToolsBundle** will only look for anonymization configurations from PHP attributes on Doctrine Entities. - -But the **DbToolsBundle** does not necessary need Doctrine ORM to anonymize your data, it can do it just with a DBAL connection. -In this case (or if you prefer YAML over attributes): you can configure the DbToolsBundle to look for anonymization -configurations in a YAML file: - -```yml -# config/packages/db_tools.yaml - -db_tools: - # ... - - anonymization: - # If you want to load configuration from a yaml: - # 1/ If you want to configure anonymization only for the default - # DBAL connection, declare it like this: - yaml: '%kernel.project_dir%/config/anonymizations.yaml' - # 2/ If you use multiple connections, declare each configuration like this: - #yaml: - #- connection_one: '%kernel.project_dir%/config/anonymizations/connection_one.yaml' - #- connection_two: '%kernel.project_dir%/config/anonymizations/connection_two.yaml' - - #... -``` - -:::tip -For more information about anonymization, refer to the [Anonymization section](./anonymization/essentials). -::: diff --git a/docs/content/configuration/basics.md b/docs/content/configuration/basics.md new file mode 100644 index 00000000..e8b7a8be --- /dev/null +++ b/docs/content/configuration/basics.md @@ -0,0 +1,657 @@ +# Configuration basics + +Configuration options will vary depending on which flavor you want to use. + +Select below your target: + + + +
+ +*DbToolsBundle* let you configure some of its behaviors. As with any classic Symfony Bundle, +all will take place in the `config/packages/db_tools.yaml` file. + +:::tip +A complete example of this file can be found in the bundle sources in: `vendor/makinacorpus/db-tools-bundle/config/packages/db_tools.yaml`. +::: + +
+ +
+ +*DbToolsBundle* let you configure some of its behaviors +all will take place in your configuration file, usually `db_tools.yaml`. + +:::tip +**In this page, all paths are relative to the `db_tools.yaml` configuration file.** + +A complete example of this file can be found in the library sources in: `vendor/makinacorpus/db-tools-bundle/config/db_tools.standalone.complete.sample.yaml`. +::: + +
+ +For detailed information about configuration options, please see the +[configuration reference](../configuration/reference). + +:::tip +**Almost every configuration option can be configured at the connection level** for example the +backup excluded tables can either be configured top-level (for all connections): + +
+ +```yml +# config/packages/db_tools.yaml +db_tools: + backup_excluded_tables: ['table1', 'table2'] +``` + +Or for each connection: + +```yml +# config/packages/db_tools.yaml +db_tools: + connections: + connection_one: + backup_excluded_tables: ['table1', 'table2'] + connection_two: + backup_excluded_tables: ['table3', 'table4'] +``` + +
+
+ +```yml +# db_tools.yaml +backup_excluded_tables: ['table1', 'table2'] +``` + +Or for each connection: + +```yml +# db_tools.yaml +connections: + connection_one: + backup_excluded_tables: ['table1', 'table2'] + connection_two: + backup_excluded_tables: ['table3', 'table4'] +``` + +
+ +When working with multiple connections, any connection which does not specify the option +will inherit from the default. +::: + +## Backup configuration + +Some options are available to customize how the `db-tools:backup` command works. + +### Storage + +#### Root directory + +The `storage_directory` parameter let you choose where to put the generated dumps. + +
+ +Default value is `'%kernel.project_dir%/var/db_tools'`. + +
+ +
+ +Default value is `./var/db_tools'`. + +
+ +#### File and directory naming strategy + +Default behavior will store your backup using this strategy: +`%storage_directory%///-.` +where `` is the file extension depending upon the database vendor (mostly `.sql` or `.dump`). + +
+ +Custom strategy can be implemented by extending the +`MakinaCorpus\DbToolsBundle\Storage\AbstractFilenameStrategy` abstract class: + +```php +namespace App\DbTools\Storage; + +use MakinaCorpus\DbToolsBundle\Storage\AbstractFilenameStrategy; + +class FooFilenameStrategy extends AbstractFilenameStrategy +{ + #[\Override] + public function generateFilename( + string $connectionName = 'default', + string $extension = 'sql', + bool $anonymized = false + ): string { + return '/some_folder/' . $connectionName . '.' . $extension; + } +} +``` + +Then registered this way, on a per-connection basis: + +```yaml +# config/packages/db_tools.yaml +db_tools: + storage: + filename_strategy: + connection_name: App\DbTools\Storage\FooFilenameStrategy +``` + +Value can be a container service identifier, or directly a class name in case this +has no constructor arguments. + +If you need to store your dumps outside of the `%storage_directory%` directory, +then implement the `MakinaCorpus\DbToolsBundle\Storage\FilenameStrategyInterface` directly +and add the following method: + +```php +namespace App\DbTools\Storage; + +use MakinaCorpus\DbToolsBundle\Storage\FilenameStrategyInterface; + +class FooFilenameStrategy implements FilenameStrategyInterface +{ + #[\Override] + public function generateFilename(/* ... */): string {} + + #[\Override] + public function getRootDir( + string $defaultRootDir, + string $connectionName = 'default', + ): string { + return '/some/path/' . $connectionName . '/foo'; + } +} +``` + +This will allow the restore command to find your backups. + +
+ +
+ +:::warning +There is as of now no way to implement a custom filename strategy when using *DbToolsBundle* as a standalone +CLI tool. + +If you need this feature, please let us know by [filing an issue](https://github.com/makinacorpus/DbToolsBundle/issues). +::: + +
+ +:::info +More filename strategies may be implemented in core in the future. If you have any +suggestions, please [open an discussion](https://github.com/makinacorpus/DbToolsBundle/issues) about it. +::: + +### Excluded tables + +The `backup_excluded_tables` parameter let you configure tables to exclude from backups. + +Default value is `null`: no table are excluded. + +
+ +Here is an example for exclude `table1` and `table2` for all connections: + +```yml +# config/packages/db_tools.yaml +db_tools: + backup_excluded_tables: ['table1', 'table2'] +``` + +Or set a specific table list for each connection: + +```yml +# config/packages/db_tools.yaml +db_tools: + connections: + connection_one: + backup_excluded_tables: ['table1', 'table2'] + connection_two: + backup_excluded_tables: ['table3', 'table4'] +``` +
+
+ +Here is an example for exclude `table1` and `table2` for all connections: + +```yml +# db_tools.yaml +backup_excluded_tables: ['table1', 'table2'] +``` + +Or set a specific table list for each connection: + +```yml +# db_tools.yaml +connections: + connection_one: + backup_excluded_tables: ['table1', 'table2'] + connection_two: + backup_excluded_tables: ['table3', 'table4'] +``` +
+ +:::tip +Note that you can override this configuration while running the `db-tools:backup` command using +the `--exclude` option. +::: + +### Binary options + +See the [default binary options](#default-binary-options) section. + +### Backup expiration age + +The `backup_expiration_age` parameter let you choose when a backup is considered as obsolete. + +Default value is `'3 months ago'`. + +Use [PHP relative date/time formats](https://www.php.net/manual/en/datetime.formats.relative.php) +for this value. + +
+ +Here is an example that sets 1 week lifetime for backups for all connections: + +```yml +# config/packages/db_tools.yaml +db_tools: + backup_expiration_age: '1 week ago' +``` + +Or set a specific value list for each connection: + +```yml +# config/packages/db_tools.yaml +db_tools: + connections: + connection_one: + backup_expiration_age: '1 week ago' + connection_two: + backup_expiration_age: '3 days ago' +``` +
+
+ +Here is an example that sets 1 week lifetime for backups for all connections: + +```yml +# db_tools.yaml +backup_expiration_age: '1 week ago' +``` + +Or set a specific value list for each connection: + +```yml +# db_tools.yaml +connections: + connection_one: + backup_expiration_age: '1 week ago' + connection_two: + backup_expiration_age: '3 days ago' +``` +
+ +### Backup and restore timeout + +The `backup_timeout` and `restore_timeout` options let you choose what is the backup and restore +processes timeout in seconds. + +Default value is `600` (seconds) for backup, `1800` (seconds) for restore. + +Value can be either a [\DateInterval::createFromDateString()](https://www.php.net/manual/en/dateinterval.createfromdatestring.php) +compatible string value or a number of seconds as an integer value. + +
+ +Here is an example that sets timeouts for all connection: + +```yml +# config/packages/db_tools.yaml +db_tools: + # As a date interval string. + backup_timeout: '6 minutes 30 seconds' + restore_timeout: '3 minutes 15 seconds' + + # As a number of seconds integer value. + backup_timeout: 390 + restore_timeout: 195 +``` + +Or set a different timeout for each connection: + +```yml +# config/packages/db_tools.yaml +db_tools: + connections: + connection_one: + backup_timeout: '6 minutes 30 seconds' + restore_timeout: '3 minutes 15 seconds' + connection_two: + backup_timeout: 390 + restore_timeout: 195 +``` +
+
+ +Here is an example that sets timeouts for all connection: + +```yml +# db_tools.yaml + +# As a date interval string. +backup_timeout: '6 minutes 30 seconds' +restore_timeout: '3 minutes 15 seconds' + +# As a number of seconds integer value. +backup_timeout: 390 +restore_timeout: 195 +``` + +Or set a different timeout for each connection: + +```yml +# db_tools.yaml +connections: + connection_one: + backup_timeout: '6 minutes 30 seconds' + restore_timeout: '3 minutes 15 seconds' + connection_two: + backup_timeout: 390 + restore_timeout: 195 +``` +
+ +## Binaries + +`db-tools:backup` and `db-tools:restore` need your system/environment to provide some extra binaries +to be able to work. These binaries depend on the database vendor you use, you will need: +* for MariaDB: `mariadb-dump` and `mariadb` +* for MySQL: `mysqldump` and `mysql` +* for PostgreSQL: `pg_dump` and `pg_restore` +* for SQLite: `sqlite3` + +You can verify if those binaries are well found by *DbToolsBundle*, +for each of your connections, by launching: + +
+ +```sh +php bin/console db-tools:check +``` +
+
+ +```sh +php vendor/bin/db-tools database:check +``` +
+ +If the `db-tools:check` command returns you some errors: + * if your binaries are present on your system but *DbToolsBundle* can't find them you will need + to specify path for these binaries: + +
+ + ```yml + # config/packages/db_tools.yaml + db_tools: + backup_binary: '/usr/local/bin/pg_dump' + restore_binary: '/usr/local/bin/pg_restore' + ``` +
+
+ + ```yml + # db_tools.yaml + backup_binary: '/usr/local/bin/pg_dump' + restore_binary: '/usr/local/bin/pg_restore' + ``` +
+ + * Backup and restore binaries, as well as command line arguments and options are + configured on a per-connection basis. If you have more than one connection, + use the following syntax instead: + +
+ + ```yml + # config/packages/db_tools.yaml + db_tools: + connections: + connection_one: + backup_binary: '/usr/local/bin/pg_dump' + restore_binary: '/usr/local/bin/pg_restore' + connection_two: + backup_binary: '/usr/local/bin/mysqldump' + restore_binary: '/usr/local/bin/mysql' + ``` +
+
+ + ```yml + # db_tools.yaml + connections: + connection_one: + backup_binary: '/usr/local/bin/pg_dump' + restore_binary: '/usr/local/bin/pg_restore' + connection_two: + backup_binary: '/usr/local/bin/mysqldump' + restore_binary: '/usr/local/bin/mysql' + ``` +
+ + * Or, if your binaries are not present on your system: you will need to install them. + +:::tip +If your app lives in the [official PHP docker image](https://hub.docker.com/_/php/), +you can install correct binaries adding these lines to your Dockerfile, + +for PostgreSQL: + +``` +RUN apt-get update && \ + apt-get install -y --no-install-recommends postgresql-client +``` + +for MariaDB/MySQL: + +``` +RUN apt-get update && \ + apt-get install -y --no-install-recommends default-mysql-client +``` +::: + +:::warning +Dump and restore is not supported yet for SQL Server. +::: + +### Default binary options + +Apart from the essential options (credentials, database name, etc.), the library +also passes a few default options to the binary depending on the operation being +performed and the invoked binary itself. You can customize those default options +by configuring your own ones per operation type and connection: + +
+ +Here is an example that sets options for all connections: + +```yml +# config/packages/db_tools.yaml +db_tools: + backup_options: '--an-option' + restore_options: '--a-first-one --a-second-one' +``` + +Or set a specific value list for each connection: + +```yml +# config/packages/db_tools.yaml +db_tools: + connections: + connection_one: + backup_options: '--an-option' + restor_options: '-xyz --another' + connection_two: + backup_options: '--a-first-one --a-second-one' + restor_options: '-O sample-value' +``` +
+
+ +Here is an example that sets options for all connections: + +```yml +# db_tools.yaml +backup_options: '--an-option' +restore_options: '--a-first-one --a-second-one' +``` + +Or set a specific value list for each connection: + +```yml +# db_tools.yaml +connections: + connection_one: + backup_options: '--an-option' + restor_options: '-xyz --another' + connection_two: + backup_options: '--a-first-one --a-second-one' + restor_options: '-O sample-value' +``` +
+ +If you do not define your own default options, the following ones will be used +according to the database vendor: + +* When backing up: + * MariaDB: `--no-tablespaces` + * MySQL: `--no-tablespaces` + * PostgreSQL: `-Z 5 --lock-wait-timeout=120` + * SQLite: `-bail` +* When restoring: + * MariaDB: None + * MySQL: None + * PostgreSQL: `-j 2 --clean --if-exists --disable-triggers` + * SQLite: None + +## Anonymizer paths + +
+ +By default, *DbToolsBundle* will look for custom *anonymizers* in 2 directories: + +* `%kernel.project_dir%/vendor/makinacorpus/db-tools-bundle/src/Anonymizer` +* `%kernel.project_dir%/src/Anonymizer` + +If you want to put custom anonymizers in another directory or if you want to load +a pack of anonymizers from an external library, you can modify/add paths: + + +```yml +# config/packages/db_tools.yaml +db_tools: + anonymizer_paths: + - '%kernel.project_dir%/src/Anonymizer' + - '%kernel.project_dir%/vendor/myAnonymizerProvider/anonymizers/src' + # ... +``` +
+
+ +By default, *DbToolsBundle* when used as a standalone CLI tool will not lookup for +custom *anonymizers*. + +If you want to write custom anonymizers, in order for them to be found, you must specify +paths where the source code lies: + + +```yml +# db_tools.yaml +db_tools: + anonymizer_paths: + - './src/Anonymizer' + - './vendor/myAnonymizerProvider/anonymizers/src' + # ... +``` +
+ +:::tip +Core provided anonymizers and anonymizers that are in packs installed using composer +will always be looked-up. +::: + +:::warning +Packs must be installed using composer: *DbToolsBundle* uses composer generated metadata +about installed packages to find them. +::: + +## Anonymization + +
+ +Per default, **DbToolsBundle** will only look for anonymization configurations from PHP attributes on Doctrine Entities. + +But *DbToolsBundle* does not necessary need Doctrine ORM to anonymize your data, it can do it just with a DBAL connection. +In this case (or if you prefer YAML over attributes): you can configure *DbToolsBundle* to look for anonymization +configurations in a YAML file: + +```yml +# config/packages/db_tools.yaml +db_tools: + + # When you have a single connection, and a single file: + anonymization_files: '%kernel.project_dir%/config/anonymizations.yaml' + + # Or with multiple connections: + anonymization_files: + connection_one: '%kernel.project_dir%/config/anonymizations/connection_one.yaml' + connection_two: '%kernel.project_dir%/config/anonymizations/connection_two.yaml' + + # Each connection may have multiple files: + anonymization_files: + connection_one: + - '%kernel.project_dir%/config/anonymizations/connection_one_1.yaml' + - '%kernel.project_dir%/config/anonymizations/connection_one_2.yaml' + # ... +``` + +
+
+ +You need to register your anonymization configuration for the anonymization feature to work: + +```yml +# config/packages/db_tools.yaml +db_tools: + + # When you have a single connection, and a single file: + anonymization_files: './anonymizations.yaml' + + # Or with multiple connections: + anonymization_files: + connection_one: './anonymizations/connection_one.yaml' + connection_two: './anonymizations/connection_two.yaml' + + # Each connection may have multiple files: + anonymization_files: + connection_one: + - './config/anonymizations/connection_one_1.yaml' + - './config/anonymizations/connection_one_2.yaml' + # ... +``` + +
+ +:::tip +For more information about anonymization and configuration file structure, refer to the [Anonymization section](../anonymization/essentials). +::: diff --git a/docs/content/configuration/reference.md b/docs/content/configuration/reference.md index a4a3fdde..e4c568a7 100644 --- a/docs/content/configuration/reference.md +++ b/docs/content/configuration/reference.md @@ -1,6 +1,10 @@ # Configuration reference -## Introduction +Configuration options will vary depending on which flavor you want to use. + +Select below your target: + + This toolset can be run in various contextes: @@ -25,77 +29,116 @@ relative to the configuration file directory the path is defined within. ::: -## All options +## Index -[`anonymization.tables` (standalone)](#anonymization-tables) | -[`anonymization.yaml`](#anonymization-yaml) | [`anonymizer_paths`](#anonymizer-paths) | +[`backup_binary`](#backup-binary) | +[`backup_excluded_tables`](#backup-excluded-tables) | [`backup_expiration_age`](#backup-expiration-age) | +[`backup_options`](#backup-options) | [`backup_timeout`](#backup-timeout) | -[`backupper_binaries`](#backupper-binaries) | -[`backupper_options`](#backupper-options) | [`connections` (standalone)](#connections) | -[`default_connection` (standalone)](#default-connection) | -[`excluded_tables`](#excluded-tables) | +[`default_connection`](#default-connection) | +[`restore_binary`](#restore-binary) | +[`restore_options`](#restore-options) | [`restore_timeout`](#restore-timeout) | -[`restorer_binaries`](#restorer-binaries) | -[`restorer_options`](#restorer-options) | -[`storage.filename_strategy`](#storage-filename-strategy) | -[`workdir` (standalone)](#workdir) +[`storage_directory`](#storage-directory) | +[`storage_filename_strategy`](#storage-filename-strategy) | +[`workdir`](#workdir) -## Common options +## `anonymizer_paths` -### `storage.root_dir` +PHP source folders in which custom anonymizer implementations will be looked-up. -Root directory of the backup storage manager. Default filename strategy will -always use this folder as a root path. +This allows you to write custom implementations and use it. -:::code-group -```yaml [Symfony] +Path are local filesystem arbitrary paths, and you are allowed to set any path. +A recursive file system iterator will lookup in those folders and find classes +that extend the `MakinaCorpus\DbToolsBundle\Anonymization\Anonymizer\AbstractAnonymizer` +class within, then register those as anonymizers. + +
+ +```yaml db_tools: - storage: - root_dir: "%kernel.root_dir%/var/db_tools" + anonymizer_paths: + - '%kernel.project_dir%/vendor/makinacorpus/db-tools-bundle/src/Anonymizer' + - '%kernel.project_dir%/src/Anonymization/Anonymizer' ``` +
+
-```yaml [Standalone] -storage: - root_dir: "./var/db_tools" +```yaml +anonymizer_paths: + - './vendor/makinacorpus/db-tools-bundle/src/Anonymizer' + - './src/Anonymization/Anonymizer' ``` + +
+ + +## `backup_binary` + +Path to backup command in filesystem. + +Defaults are the well known executable names without absolute file path, which should +work in most Linux distributions. + + +
+ +```yaml +db_tools: + backup_binary: /usr/bin/pg_dump +``` +
+
+ +```yaml +backup_binary: /usr/bin/pg_dump +``` + +
+ +:::warning +This top level parameter applies to all connections per default. +If you need a different value per connection, the setting can also be configured on a +per connection basis under the `connections.CONNECTION.backup_binary` name. + +If you have more than one connection using different database vendor, it is strongly +advised to override at the connection level. ::: -### `storage.filename_strategy` -Key value pairs, keys are connection names, values can be either: -- `default`: let the tool decide, it is an alias to `datetime`. -- `datetime`: stores backups in split timestamp directory tree, such as: `/YYYY/MM/-.` +## `backup_excluded_tables` -When used in a Symfony application, the strategy can be a service name registered in the -container. This service must implement `MakinaCorpus\DbToolsBundle\Storage\FilenameStrategyInterface`. -See [filename strategies documentation](../backup_restore) for more information. +Tables excluded from backup. Example: -:::code-group -```yaml [Symfony] +
+ +```yaml db_tools: - storage: - filename_strategy: - connection_one: datetime - connection_two: default - connection_three: app.my_filename_strategy - connection_four: App\DbTools\Storage\MyCustomFilenameStrategy + backup_excluded_tables: ['table1', 'table2'] ``` +
+
-```yaml [Standalone] -storage: - filename_strategy: - connection_one: datetime - connection_two: default - connection_four: App\DbTools\Storage\MyCustomFilenameStrategy +```yaml +backup_excluded_tables: ['table1', 'table2'] ``` + +
+ +:::tip +This top level parameter applies to all connections per default. +If you need a different value per connection, the setting can also be configured on a +per connection basis under the `connections.CONNECTION.backup_excluded_tables` name. ::: -### `backup_expiration_age` + +## `backup_expiration_age` Backup file expiration time after which they get deleted when running the `backup` or `clean` command. @@ -104,18 +147,67 @@ It uses a relative date interval format as documented in https://www.php.net/man Example: -:::code-group -```yaml [Symfony] +
+ +```yaml db_tools: backup_expiration_age: '6 months ago' ``` +
+
-```yaml [Standalone] +```yaml backup_expiration_age: '6 months ago' ``` + +
+ +:::tip +This top level parameter applies to all connections per default. +If you need a different value per connection, the setting can also be configured on a +per connection basis under the `connections.CONNECTION.backup_expiration_age` name. ::: -### `backup_timeout` + +## `backup_options` + +Allows you to add specific command line options to the backup command. + +If you do not define some default options, here or by using the "--extra-options" option when +invoking the command, the following ones will be used according to the database vendor: + - MariaDB: `--no-tablespaces` + - MySQL: `--no-tablespaces` + - PostgreSQL: `-Z 5 --lock-wait-timeout=120` + - SQLite: `-bail` + +By specifying options, the default ones will be dropped. + +
+ +```yaml +db_tools: + backup_options: '-Z 5 --lock-wait-timeout=120' +``` +
+
+ +```yaml +backup_options: '-Z 5 --lock-wait-timeout=120' +``` + +
+ +:::warning +This top level parameter applies to all connections per default. +If you need a different value per connection, the setting can also be configured on a +per connection basis under the `connections.CONNECTION.backup_options` name. + +If you have more than one connection using different database vendor, it is strongly +advised to override at the connection level. +::: + + +## `backup_timeout` Backup process timeout in seconds. @@ -124,8 +216,9 @@ or accepts a number of seconds as an integer value. Example: -:::code-group -```yaml [Symfony] +
+ +```yaml # As a date interval string. db_tools: backup_timeout: '2 minutes and 7 seconds' @@ -134,131 +227,165 @@ db_tools: db_tools: backup_timeout: 67 ``` +
+
-```yaml [Standalone] +```yaml # As a date interval string. backup_timeout: '2 minutes and 7 seconds' # As a number of seconds. backup_timeout: 67 ``` + +
+ +:::tip +This top level parameter applies to all connections per default. +If you need a different value per connection, the setting can also be configured on a +per connection basis under the `connections.CONNECTION.backup_timeout` name. ::: -### `excluded_tables` -Tables excluded from backup. +## `connections` -Example: +All reachable connection list, with their an URL connection string. -:::code-group -```yaml [Symfony] -db_tools: - excluded_tables: - connection_one: ['table1', 'table2'] - connection_two: ['table1', 'table2'] -``` +In standalone mode, connections are handled by `makinacorpus/query-builder`. -```yaml [Symfony alt.] +When using a Symfony bundle, all connections from the Doctrine bundle using +Doctrine DBAL will be automatically registered, you need this section only if +you need to add connection specific options. + +
+ +```yaml +# With connection specific options. db_tools: - # If you have a single connection. - excluded_tables: ['table1', 'table2'] + connections: + connection_one: + # ... Apply here connection-specific options. + # @todo Add here all available options. ``` +
+
-```yaml [Standalone] -excluded_tables: - connection_one: ['table1', 'table2'] - connection_two: ['table1', 'table2'] -``` +```yaml +# With connection specific options. +connections: + connection_one: + url: "pgsql://username:password@hostname:port?version=16.0&other_option=..." + # ... Apply here connection-specific options. + # @todo Add here all available options. + connection_two: #... + +# With all default options, only database DSN. +connections: + connection_two: "mysql://username:password@hostname:port?version=8.1&other_option=..." + connection_two: #... -```yaml [Standalone alt.] - # If you have a single connection. - excluded_tables: ['table1', 'table2'] +# With a single connection. +# Connection name will be "default". +connections: "pgsql://username:password@hostname:port?version=16.0&other_option=..." ``` -::: +
-### `backupper_binaries` -Path to backup command in filesystem. +## `default_connection` -Defaults are the well known executable names without absolute file path, which should -work in most Linux distributions. +Default connection name when connection is unspecified in the command line. + +If none set, the first one in list will be used instead. + +When using a Symfony bundle, the Doctrine bundle default connection is set to +be the default if this option is not specified. +
-:::code-group -```yaml [Symfony] +```yaml db_tools: - backupper_binaries: - mariadb: /usr/bin/mariadb-dump - mysql: /usr/bin/mysqldump - postgresql: /usr/bin/pg_dump - sqlite: /usr/bin/sqlite3 + default_connection: connection_one ``` +
+
-```yaml [Standalone] -backupper_binaries: - mariadb: /usr/bin/mariadb-dump - mysql: /usr/bin/mysqldump - postgresql: /usr/bin/pg_dump - sqlite: /usr/bin/sqlite3 +```yaml +default_connection: connection_one ``` -::: -### `restorer_binaries` +
+ + +## `restore_binary` Path to restore command in filesystem. Defaults are the well known executable names without absolute file path, which should work in most Linux distributions. -:::code-group -```yaml [Symfony] +
+ +```yaml db_tools: - restorer_binaries: - mariadb: /usr/bin/mariadb - mysql: /usr/bin/mysql - postgresql: /usr/bin/pg_restore - sqlite: /usr/bin/sqlite3 + restore_binary: /usr/bin/pg_restore ``` +
+
-```yaml [Standalone] -restorer_binaries: - mariadb: /usr/bin/mariadb - mysql: /usr/bin/mysql - postgresql: /usr/bin/pg_restore - sqlite: /usr/bin/sqlite3 +```yaml +restore_binary: /usr/bin/pg_restore ``` + +
+ +:::warning +This top level parameter applies to all connections per default. +If you need a different value per connection, the setting can also be configured on a +per connection basis under the `connections.CONNECTION.restore_binary` name. + +If you have more than one connection using different database vendor, it is strongly +advised to override at the connection level. ::: -### `backupper_options` -Allows you to add specific command line options to the backup command, one for each connection. +## `restore_options` + +Allows you to add specific command line options to the restore command. If you do not define some default options, here or by using the "--extra-options" option when invoking the command, the following ones will be used according to the database vendor: - - MariaDB: `--no-tablespaces` - - MySQL: `--no-tablespaces` - - PostgreSQL: `-Z 5 --lock-wait-timeout=120` - - SQLite: `-bail` + - MariaDB: None + - MySQL: None + - PostgreSQL: `-j 2 --clean --if-exists --disable-triggers` + - SQLite: None -By specifying options, the default ones will be dropped. +
-:::code-group -```yaml [Symfony] +```yaml db_tools: - backupper_options: - connection_one: '-Z 5 --lock-wait-timeout=120' - connection_two: '--no-tablespaces' + restore_options: '-j 2 --clean --if-exists --disable-triggers' ``` +
+
-```yaml [Standalone] -backupper_options: - connection_one: '-Z 5 --lock-wait-timeout=120' - connection_two: '--no-tablespaces' +```yaml +restore_options: '-j 2 --clean --if-exists --disable-triggers' ``` + +
+ +:::warning +This top level parameter applies to all connections per default. +If you need a different value per connection, the setting can also be configured on a +per connection basis under the `connections.CONNECTION.restore_options` name. + +If you have more than one connection using different database vendor, it is strongly +advised to override at the connection level. ::: -### `restore_timeout` + +## `restore_timeout` Restore process timeout in seconds. @@ -267,8 +394,9 @@ or accepts a number of seconds as an integer value. Example: -:::code-group -```yaml [Symfony] +
+ +```yaml # As a date interval string. db_tools: restore_timeout: '2 minutes and 7 seconds' @@ -277,162 +405,129 @@ db_tools: db_tools: restore_timeout: 67 ``` +
+
-```yaml [Standalone] +```yaml # As a date interval string. restore_timeout: '2 minutes and 7 seconds' # As a number of seconds. restore_timeout: 67 ``` + +
+ +:::tip +This top level parameter applies to all connections per default. +If you need a different value per connection, the setting can also be configured on a +per connection basis under the `connections.CONNECTION.restore_timeout` name. ::: -### `restorer_options` -Allows you to add specific command line options to the restore command, one for each connection. +## `storage_directory` -If you do not define some default options, here or by using the "--extra-options" option when -invoking the command, the following ones will be used according to the database vendor: - - MariaDB: None - - MySQL: None - - PostgreSQL: `-j 2 --clean --if-exists --disable-triggers` - - SQLite: None +Root directory of the backup storage manager. Default filename strategy will +always use this folder as a root path. + +
-:::code-group -```yaml [Symfony] +```yaml db_tools: - backupper_options: - connection_one: '-j 2 --clean --if-exists --disable-triggers' - connection_two: '--no-tablespaces' + storage_directory: "%kernel.root_dir%/var/db_tools" ``` +
+
-```yaml [Standalone] -backupper_options: - connection_one: '-j 2 --clean --if-exists --disable-triggers' - connection_two: '--some-other-option +```yaml +storage_directory: "./var/db_tools" ``` -::: -### `anonymizer_paths` +
-PHP source folders in which custom anonymizer implementations will be looked-up. +:::tip +This top level parameter applies to all connections per default. +If you need a different value per connection, the setting can also be configured on a +per connection basis under the `connections.CONNECTION.storage_directory` name. +::: -This allows you to write custom implementations and use it. -Path are local filesystem arbitrary paths, and you are allowed to set any path. -A recursive file system iterator will lookup in those folders and find classes -that extend the `MakinaCorpus\DbToolsBundle\Anonymization\Anonymizer\AbstractAnonymizer` -class within, then register those as anonymizers. +## `storage.filename_strategy` -:::code-group -```yaml [Symfony] -db_tools: - anonymizer_paths: - - '%kernel.project_dir%/vendor/makinacorpus/db-tools-bundle/src/Anonymizer' - - '%kernel.project_dir%/src/Anonymization/Anonymizer' -``` +Default backup filename strategy that will generate the backup file names. -```yaml [Standalone] - anonymizer_paths: - - './vendor/makinacorpus/db-tools-bundle/src/Anonymizer' - - './src/Anonymization/Anonymizer' -``` -::: +Generated backup filenames will always be relative to the connection or global +root directory. Available options are: +- `default`: let the tool decide, it is an alias to `datetime`. +- `datetime`: stores backups in split timestamp directory tree, such as: `/YYYY/MM/-.` +- any class name implementing the `MakinaCorpus\DbToolsBundle\Storage\FilenameStrategyInterface` interface. -### `anonymization.yaml` +When used in a Symfony application, the strategy can be a service name registered in the +container. This service must implement `MakinaCorpus\DbToolsBundle\Storage\FilenameStrategyInterface`. +See [filename strategies documentation](../backup_restore) for more information. -List of YAML configuration file that contains table and their columns to -anonymize. +Example: -For configuration format please refer the [anonymizers documentation](../anonymization/core-anonymizers). +
-:::code-group -```yaml [Symfony] +```yaml +# Default value, `default` is an alias of `datetime`. db_tools: - anonymizer: - yaml: - - connection_one: '%kernel.project_dir%/config/anonymizations/connection_one.yaml' - - connection_two: '%kernel.project_dir%/config/anonymizations/connection_two.yaml' -``` + storage_filename_strategy: default -```yaml [Symfony alt.] +# Explicit default. db_tools: - anonymizer: - # If you have a single connection. - yaml: '%kernel.project_dir%/config/anonymizations.yaml' -``` + storage_filename_strategy: datetime -```yaml [Standalone] -anonymizer: - yaml: - - connection_one: './db_tools.connection_one.anonymization.yaml' - - connection_two: './db_tools.connection_two.anonymization.yaml' -``` +# Using a service name. +db_tools: + storage_filename_strategy: app.my_filename_strategy -```yaml [Standalone alt.] -anonymizer: - yaml: './db_tools.anonymization.yaml' +# Using a class name. +db_tools: + storage_filename_strategy: App\DbTools\Storage\MyCustomFilenameStrategy ``` -::: +
+
-## Symfony bundle specific options +```yaml +# Default value, `default` is an alias of `datetime`. +storage_filename_strategy: default -None yet, all options can be used in the standalone console version as well. +# Explicit default. +storage_filename_strategy: datetime -## Standalone specific options - -### `workdir` - -Default path in which all relative file system path found in the same config -path will be relative to. - -If none set, directory in which the configuration file is will be used instead. +# Using a service name. +storage_filename_strategy: app.my_filename_strategy -:::code-group -```yaml [Standalone] -workdir: /some/project/path/config +# Using a class name. +storage_filename_strategy: App\DbTools\Storage\MyCustomFilenameStrategy ``` -::: - -### `connections` -All reachable connection list, with their an URL connection string. +
-In standalone mode, connections are handled by `makinacorpus/query-builder`. +:::tip +This top level parameter applies to all connections per default. +If you need a different value per connection, the setting can also be configured on a +per connection basis under the `connections.CONNECTION.storage_filename_strategy` name. +::: -```yaml [Standalone] -connections: - connection_one: "pgsql://username:password@hostname:port?version=16.0&other_option=..." - connection_two: "mysql://username:password@hostname:port?version=8.1&other_option=..." -# Connection name will be "default" -connections: "pgsql://username:password@hostname:port?version=16.0&other_option=..." -``` +## `workdir` -### `default_connection` +Default path in which all relative file system path found in the same config +path will be relative to. -Default connection name when connection is unspecified in the command line. +If none set, directory in which the configuration file is will be used instead. -If none set, the first one in list will be used instead. +
-```yaml [Standalone] -default_connection: connection_one +```yaml +workdir: /some/project/path/config ``` -### `anonymization.tables` +
-You can write anonymization configuration directly in the configuration file when -using the standalone mode. This prevent configuration file profileration. - -Configuration file can be dumped from the Symfony bundle, then used with the -standalone connection. - -```yaml [Standalone] -anonymization: - tables: - connection_one: - table_name: - column_name: - anonymizer: anonymizer_name - # ... other options... -``` +:::tip +This options is specific for standalone usage. +::: diff --git a/docs/content/contribute/pack.md b/docs/content/contribute/pack.md index ab3921a5..1c9978b2 100644 --- a/docs/content/contribute/pack.md +++ b/docs/content/contribute/pack.md @@ -20,7 +20,7 @@ First, you will need to adapt the provided `composer.json`: { "name": "db-tools-bundle/pack-template",// [!code --] "name": "my-vendor/pack-awesome",// [!code ++] - "description": "An example pack of anonymizers for the DbToolsBundle",// [!code --] + "description": "An example pack of anonymizers for DbToolsBundle",// [!code --] "description": "An awesome pack for anonymizing many things!",// [!code ++] "type": "db-tools-bundle-pack", "license": "MIT", @@ -130,7 +130,7 @@ Learn more about how to develop them reading the [Custom Anonymizers section](.. ## 3. Test your anonymizers After you built your anonymizers, don't forget to test them. We recommend doing at least one functionnal test per anonymizer. -To inspire you doing these tests, read [existing tests in the DbToolsBundle](https://github.com/makinacorpus/DbToolsBundle/tree/main/tests/Functional/Anonymizer/Core) +To inspire you doing these tests, read [existing tests in DbToolsBundle](https://github.com/makinacorpus/DbToolsBundle/tree/main/tests/Functional/Anonymizer/Core) or in official packs. To help you launchning these tests, use provided `dev.sh` script, see [Development guide section](./guide) to learn how to use it. diff --git a/docs/content/getting-started/basics.md b/docs/content/getting-started/basics.md index 81d37744..e084fd91 100644 --- a/docs/content/getting-started/basics.md +++ b/docs/content/getting-started/basics.md @@ -97,12 +97,13 @@ anonymization:
-With the DbToolsBundle, by adding some PHP attributes on your Doctrine Entities, + +With *DbToolsBundle*, by adding some PHP attributes on your Doctrine Entities, you can easily configure a complete anonymization for your sensitive data. ::: info Anonymization does not only work with Doctrine Entities. You can use it with -*any* database and [configure it with YAML](../configuration#anonymization). All you need is a DBAL connection. +*any* database and [configure it with YAML](../configuration/basics#anonymization). All you need is a DBAL connection. ::: ```php @@ -167,7 +168,7 @@ to download and restore it on your local environment without any security concer We know that a slow anonymization process can be real pain. That's why a meticulous work has been carried out to make this operation as quick as possible. -Thanks to this work, the DbToolsBundle can now **anonymize 1 million rows in less than 20s**! +Thanks to this work, *DbToolsBundle* can now **anonymize 1 million rows in less than 20s**! Learn more about performance in the [dedicated section](../anonymization/performance). ::: diff --git a/docs/content/getting-started/flavors.md b/docs/content/getting-started/flavors.md index 193fb1f3..23811fbb 100644 --- a/docs/content/getting-started/flavors.md +++ b/docs/content/getting-started/flavors.md @@ -31,7 +31,7 @@ to find the database(s) you want to manage. be fully integrated into any Symfony project via its dedicated bridge. After you installed the bundle: -* All the *DbToolsBundle* commands will be accessible with +* All *DbToolsBundle* commands will be accessible with the [Symfony Console](https://symfony.com/doc/current/components/console.html). * Database connection URL will be autoconfigured based on available DBAL connections. * *DbToolsBundle* can be setup through its bundle configuration (`config/packages/db_tools.yaml`). diff --git a/docs/content/getting-started/installation.md b/docs/content/getting-started/installation.md index db237bd6..f6507296 100644 --- a/docs/content/getting-started/installation.md +++ b/docs/content/getting-started/installation.md @@ -24,7 +24,7 @@ you should not be lost if you are a regular Symfony developer. - PHP 8.1 or higher - Symfony 6.0 or higher -- Doctrine/DBAL, the DbToolsBundle takes advantage of available DBAL connections +- Doctrine/DBAL, *DbToolsBundle* takes advantage of available DBAL connections
@@ -118,7 +118,7 @@ php bin/console db-tools:check
:::tip -If this command returns some errors, go to the [binaries configuration](../configuration#binaries) +If this command returns some errors, go to the [binaries configuration](../configuration/basics#binaries) section to understand how to solve them. :::