From ed9e4d512cfb80dfae4e2a457bf72aeccede4c21 Mon Sep 17 00:00:00 2001 From: Pierre Rineau Date: Wed, 27 Nov 2024 15:08:30 +0100 Subject: [PATCH] issue #194 - missing parameters in configuration reference --- .../db_tools.standalone.complete.sample.yaml | 2 +- docs/content/configuration/reference.md | 199 ++++++++++++++++-- 2 files changed, 178 insertions(+), 23 deletions(-) diff --git a/config/db_tools.standalone.complete.sample.yaml b/config/db_tools.standalone.complete.sample.yaml index 058ce3cb..3301a9fe 100644 --- a/config/db_tools.standalone.complete.sample.yaml +++ b/config/db_tools.standalone.complete.sample.yaml @@ -104,7 +104,7 @@ anonymization: anonymizer: anonymizer_name # ... anonymizer specific options... column2: - # ... + # ... table2: # ... connection_two: diff --git a/docs/content/configuration/reference.md b/docs/content/configuration/reference.md index e4c568a7..365000a6 100644 --- a/docs/content/configuration/reference.md +++ b/docs/content/configuration/reference.md @@ -29,22 +29,135 @@ relative to the configuration file directory the path is defined within. ::: -## Index - -[`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) | -[`connections` (standalone)](#connections) | -[`default_connection`](#default-connection) | -[`restore_binary`](#restore-binary) | -[`restore_options`](#restore-options) | -[`restore_timeout`](#restore-timeout) | -[`storage_directory`](#storage-directory) | -[`storage_filename_strategy`](#storage-filename-strategy) | -[`workdir`](#workdir) +
+ + [[toc]] + +
+ + + +## `anonymization` + +Write the anonymization configuration directly in the main configuration file. + +Keys under the first dimension are connections names, then follows the structure +expected in anonymization configuration files. + +
+ +```yaml +# When you have a single connection, and a single file: +db_tools: + anonymization: + connection_one: + table1: + column1: + anonymizer: anonymizer_name + # ... anonymizer specific options... + column2: + # ... + table2: + # ... + connection_two: + # ... +``` +
+
+ +```yaml +anonymization: + connection_one: + table1: + column1: + anonymizer: anonymizer_name + # ... anonymizer specific options... + column2: + # ... + table2: + # ... + connection_two: + # ... +``` + +
+ +:::tip +For more information about anonymization structure, refer to the [Anonymization section](../anonymization/essentials). +::: + + + +## `anonymization_files` + +Files that contains anonymization configuration. + +
+ +```yaml +# When you have a single connection, and a single file: +db_tools: + anonymization_files: '%kernel.project_dir%/config/anonymizations.yaml' + +# Or with multiple connections: +db_tools: + 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: +db_tools: + anonymization_files: + connection_one: + - '%kernel.project_dir%/config/anonymizations/connection_one_1.yaml' + - '%kernel.project_dir%/config/anonymizations/connection_one_2.yaml' + # ... +``` + +:::tip +File paths must be absolute, use Symfony parameters to refer the project root. +::: + +
+
+ +```yaml +# 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: + - './anonymizations/connection_one_1.yaml' + - './anonymizations/connection_one_2.yaml' + # ... +``` + +:::tip +File paths can be relative, any relative path will be relative to this configuration +file directory. +::: + +
+ +:::tip +For more information about anonymization and configuration file structure, refer to the [Anonymization section](../anonymization/essentials). +::: + ## `anonymizer_paths` @@ -65,6 +178,11 @@ db_tools: - '%kernel.project_dir%/vendor/makinacorpus/db-tools-bundle/src/Anonymizer' - '%kernel.project_dir%/src/Anonymization/Anonymizer' ``` + +:::tip +File paths must be absolute, use Symfony parameters to refer the project root. +::: +
@@ -74,6 +192,11 @@ anonymizer_paths: - './src/Anonymization/Anonymizer' ``` +:::tip +File paths can be relative, any relative path will be relative to this configuration +file directory. +::: +
@@ -260,12 +383,20 @@ you need to add connection specific options.
```yaml -# With connection specific options. db_tools: connections: connection_one: - # ... Apply here connection-specific options. - # @todo Add here all available options. + # Complete list of accepted parameters follows. + backup_binary: /usr/local/bin/vendor-one-dump + backup_excluded_tables: ['table_one', 'table_two'] + backup_expiration_age: '1 month ago' + backup_options: --no-table-lock + backup_timeout: 2000 + restore_binary: /usr/local/bin/vendor-one-restore + restore_options: --disable-triggers --other-option + restore_timeout: 5000 + storage_directory: /path/to/storage + storage_filename_strategy: datetime ```
@@ -274,10 +405,24 @@ db_tools: # With connection specific options. connections: connection_one: + # Connection URL for connecting. + # Please refer to makinacorpus/db-query-builder or documentation for more information. + # Any URL built for doctrine/dbal usage should work. + # URL is the sole mandatory parameter. + # Complete list of accepted parameters follows. url: "pgsql://username:password@hostname:port?version=16.0&other_option=..." - # ... Apply here connection-specific options. - # @todo Add here all available options. - connection_two: #... + backup_binary: /usr/local/bin/vendor-one-dump + backup_excluded_tables: ['table_one', 'table_two'] + backup_expiration_age: '1 month ago' + backup_options: --no-table-lock + backup_timeout: 2000 + restore_binary: /usr/local/bin/vendor-one-restore + restore_options: --disable-triggers --other-option + restore_timeout: 5000 + storage_directory: /path/to/storage + storage_filename_strategy: datetime + connection_two: + #... # With all default options, only database DSN. connections: @@ -289,8 +434,18 @@ connections: connections: "pgsql://username:password@hostname:port?version=16.0&other_option=..." ``` +:::warning +If you configure this parameter with a single URL string with no connection names, +the connection name will be `default`. +::: +
+:::tip +All parameters for each connection are the exact same as the top-level parameters +documented in this file. +::: + ## `default_connection`