Skip to content

Commit

Permalink
Issue #178 - Document the usage of the library with Laravel
Browse files Browse the repository at this point in the history
  • Loading branch information
@Lonnytunes
Lonnytunes committed Dec 3, 2024
1 parent 786ce22 commit 40fd64f
Show file tree
Hide file tree
Showing 4 changed files with 502 additions and 16 deletions.
3 changes: 1 addition & 2 deletions docs/.vitepress/theme/components/DbToolsBundleFlavorSwitcher.vue
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,13 +19,12 @@ const id = Math.random().toString(36).substring(2, 6);
</svg>
Symfony
</label>
<input type="radio" :id="'laravel-' + id" :name="'flavor-' + id" value="laravel" disabled>
<input type="radio" :id="'laravel-' + id" :name="'flavor-' + id" value="laravel" v-model="flavor">
<label :for="'laravel-' + id">
<svg width="20px" height="20px" viewBox="0 0 32 32" version="1.1" xmlns="http://www.w3.org/2000/svg">
<path d="M13.143 23.585l10.46-5.97-4.752-2.736-10.453 6.019zM24.084 11.374l-4.757-2.736v5.417l4.758 2.737zM24.559 5.078l-4.756 2.736 4.756 2.736 4.755-2.737zM9.911 18.928l2.76-1.589v-11.934l-4.758 2.738v11.934zM7.437 1.846l-4.756 2.737 4.756 2.737 4.753-2.737zM2.204 5.406v18.452l10.464 6.022v-5.471l-5.472-3.096c-0.018-0.013-0.032-0.027-0.051-0.039-0.014-0.013-0.030-0.023-0.044-0.034l-0.001-0.003c-0.015-0.015-0.028-0.031-0.039-0.049l-0.001-0.001c-0.014-0.013-0.025-0.028-0.035-0.045l-0.001-0.001h-0.003c-0.008-0.015-0.016-0.035-0.024-0.055l-0.001-0.004c-0.007-0.015-0.015-0.032-0.022-0.051l-0.001-0.003c-0.004-0.020-0.008-0.045-0.010-0.070l-0-0.002c-0.003-0.015-0.006-0.033-0.008-0.051l-0-0.001v-12.759l-2.757-1.59zM24.085 23.857v-5.422l-10.464 5.974v5.47zM29.789 14.055v-5.417l-4.756 2.737v5.417zM30.725 7.69c0.011 0.038 0.018 0.081 0.018 0.126v0 6.513c-0 0.176-0.095 0.329-0.237 0.411l-0.002 0.001-5.468 3.149v6.241c-0 0.175-0.095 0.328-0.236 0.411l-0.002 0.001-11.416 6.57c-0.024 0.013-0.052 0.025-0.081 0.033l-0.003 0.001-0.030 0.013c-0.036 0.011-0.078 0.017-0.121 0.017s-0.085-0.006-0.125-0.018l0.003 0.001c-0.015-0.004-0.027-0.009-0.039-0.016l0.001 0.001c-0.031-0.011-0.057-0.021-0.082-0.033l0.004 0.002-11.413-6.57c-0.144-0.084-0.239-0.237-0.239-0.412v0-19.548c0-0.044 0.007-0.087 0.019-0.127l-0.001 0.003c0.004-0.015 0.013-0.025 0.018-0.040 0.009-0.029 0.019-0.053 0.030-0.076l-0.001 0.003c0.008-0.016 0.018-0.030 0.029-0.042l-0 0 0.042-0.057 0.047-0.034c0.018-0.015 0.034-0.030 0.052-0.043h0.001l5.708-3.285c0.068-0.040 0.15-0.064 0.237-0.064s0.169 0.024 0.239 0.065l-0.002-0.001 5.71 3.285c0.019 0.013 0.035 0.027 0.051 0.042l-0-0 0.048 0.034c0.016 0.018 0.025 0.038 0.042 0.057 0.012 0.012 0.022 0.026 0.031 0.041l0.001 0.001c0.010 0.020 0.020 0.044 0.029 0.069l0.001 0.004 0.016 0.040c0.011 0.035 0.018 0.076 0.018 0.118 0 0.002 0 0.004-0 0.006v-0 12.208l4.756-2.737v-6.241c0-0.001 0-0.002 0-0.002 0-0.043 0.006-0.085 0.017-0.125l-0.001 0.003c0.004-0.013 0.013-0.025 0.016-0.040 0.010-0.030 0.020-0.054 0.032-0.078l-0.002 0.004c0.009-0.015 0.023-0.025 0.032-0.042 0.015-0.019 0.027-0.038 0.042-0.054 0.014-0.013 0.029-0.025 0.045-0.035l0.001-0.001c0.018-0.013 0.033-0.029 0.052-0.040h0.001l5.708-3.286c0.068-0.040 0.15-0.064 0.237-0.064s0.169 0.024 0.239 0.065l-0.002-0.001 5.708 3.286c0.020 0.013 0.034 0.027 0.053 0.039 0.015 0.013 0.032 0.023 0.046 0.035 0.016 0.018 0.028 0.038 0.043 0.056 0.011 0.012 0.021 0.026 0.030 0.040l0.001 0.001c0.012 0.022 0.022 0.047 0.030 0.073l0.001 0.003c0.008 0.012 0.014 0.025 0.019 0.039l0 0.001z"/>
</svg>
Laravel
<small>(soon)</small>
</label>
<input type="radio" :id="'docker-' + id" :name="'flavor-' + id" value="docker" disabled>
<label :for="'docker-' + id">
Expand Down
134 changes: 121 additions & 13 deletions docs/content/backup_restore.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,15 +5,16 @@ 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/basics#binaries) for your
database vendor with correct parameters to dump your database.
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/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/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).
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).

<div class="standalone">

Expand All @@ -28,6 +29,13 @@ vendor/bin/db-tools backup
php bin/console db-tools:backup
```

</div>
<div class="laravel">

```sh
php artisan db-tools:backup
```

</div>

You can specify the behavior of the command with some options detailed below.
Expand Down Expand Up @@ -56,6 +64,18 @@ You can choose to back up a database from another connection with `--connection`
php bin/console db-tools:backup --connection other_connection_name
```

</div>
<div class="laravel">

By default, the command will back up the database from the default connection.

You can choose to back up a database from another connection with `--connection`
option:

```sh
php artisan db-tools:backup --connection other_connection_name
```

</div>

### Excluded tables
Expand Down Expand Up @@ -86,6 +106,17 @@ php bin/console db-tools:backup --excluded-table table_to_exclude
php bin/console db-tools:backup --excluded-table table_to_exclude_1 --excluded-table table_to_exclude_2
```

</div>
<div class="laravel">

```sh
# Exclude a table
php artisan db-tools:backup --excluded-table table_to_exclude

# Or more
php artisan db-tools:backup --excluded-table table_to_exclude_1 --excluded-table table_to_exclude_2
```

</div>

### No cleanup
Expand All @@ -105,6 +136,13 @@ vendor/bin/db-tools backup --no-cleanup
php bin/console db-tools:backup --no-cleanup
```

</div>
<div class="laravel">

```sh
php artisan db-tools:backup --no-cleanup
```

</div>

:::warning
Expand All @@ -129,6 +167,13 @@ vendor/bin/db-tools backup --extra-options "--opt1 val1 --opt2 val2 --flag"
php bin/console db-tools:backup --extra-options "--opt1 val1 --opt2 val2 --flag"
```

</div>
<div class="laravel">

```sh
php artisan db-tools:backup --extra-options "--opt1 val1 --opt2 val2 --flag"
```

</div>

Unless you specify the `--ignore-default-options` option, the custom options
Expand All @@ -154,12 +199,21 @@ vendor/bin/db-tools backup --ignore-default-options
php bin/console db-tools:backup --ignore-default-options
```

</div>
<div class="laravel">

```sh
# Will run a backup without any special options except essential ones:
php artisan db-tools:backup --ignore-default-options
```

</div>

## Restore command

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.
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.

<div class="standalone">

Expand All @@ -174,6 +228,13 @@ vendor/bin/db-tools restore
php bin/console db-tools:restore
```

</div>
<div class="laravel">

```sh
php artisan db-tools:restore
```

</div>

You can specify the behavior of the command with some options detailed below.
Expand Down Expand Up @@ -202,6 +263,18 @@ You can choose to restore a database from another connection with `--connection`
php bin/console db-tools:restore --connection other_connection_name
```

</div>
<div class="laravel">

By default, the command will restore the database from the default connection.

You can choose to restore a database from another connection with `--connection`
option:

```sh
php artisan db-tools:restore --connection other_connection_name
```

</div>

### Filename
Expand All @@ -225,6 +298,13 @@ vendor/bin/db-tools restore --filename /path/to/my/backup.sql
php bin/console db-tools:restore --filename /path/to/my/backup.sql
```

</div>
<div class="laravel">

```sh
php artisan db-tools:restore --filename /path/to/my/backup.sql
```

</div>

### Force
Expand All @@ -246,6 +326,13 @@ vendor/bin/db-tools restore --force
php bin/console db-tools:restore --force
```

</div>
<div class="laravel">

```sh
php artisan db-tools:restore --force
```

</div>

:::danger
Expand Down Expand Up @@ -277,6 +364,13 @@ vendor/bin/db-tools restore --extra-options "--opt1 val1 --opt2 val2 --flag"
php bin/console db-tools:restore --extra-options "--opt1 val1 --opt2 val2 --flag"
```

</div>
<div class="laravel">

```sh
php artisan db-tools:restore --extra-options "--opt1 val1 --opt2 val2 --flag"
```

</div>

Unless you specify the `--ignore-default-options` option, the custom options
Expand All @@ -303,20 +397,34 @@ php bin/console db-tools:restore --ignore-default-options
```

</div>
<div class="laravel">

```sh
# Will run a restoration without any special options except essential ones:
php artisan db-tools:restore --ignore-default-options
```

</div>

## Storage

As mentioned earlier on this page, *DbToolsBundle* can list existing backup files
when you want to restore a previous one with the restore command.
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 <span class="standalone">`./var/db_tools` (relative to the yaml config file)</span><span class="symfony">`%kernel.project_dir%/var/db_tools`</span>
All backups are stored in a directory. By default this directory is
<span class="standalone">`./var/db_tools` (relative to the yaml config file)</span>
<span class="symfony">`%kernel.project_dir%/var/db_tools`</span>
<span class="laravel">`<project-dir>/storage/db_tools`</span>
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.
In this directory, each backup is put in subdirectories depending on the backup
date. The backup's filename is generated from the backup date and the database
connection name.

For a backup made the 2023-05-15 at 12:22:35 for the default connection, the filename will be :
<span class="standalone">`./var/db_tools/2023/05/default-20230515122235.sql`</span><span class="symfony">`%kernel.project_dir%/var/db_tools/2023/05/default-20230515122235.sql`</span>.
For a backup made the 2023-05-15 at 12:22:35 for the default connection,
the filename will be:
<span class="standalone">`./var/db_tools/2023/05/default-20230515122235.sql`</span>
<span class="symfony">`%kernel.project_dir%/var/db_tools/2023/05/default-20230515122235.sql`</span>
<span class="laravel">`<project-dir>/storage/db_tools/2023/05/default-20230515122235.sql`</span>.

Note that the file extension may vary depending on the database vendor.
Loading

0 comments on commit 40fd64f

Please sign in to comment.