Implement new database command for the registry CLI
Context
With the development of the registry metadata database (&2313 (closed)), we need to introduce a set of new operations on the registry CLI to allow developers, users, and administrators to do two main things:
- Import metadata from the filesystem into the database. This is a one-off process;
- Manage database migrations.
Currently, the registry CLI has the following commands:
| Name | Description |
|---|---|
garbage-collect |
"`garbage-collect` deletes layers not referenced by any manifests" |
serve |
"`serve` stores and distributes Docker images" |
The garbage-collect command has the following options:
| Short | Long | Description |
|---|---|---|
-s |
--debug-serve |
"run a pprof debug server at <address:port>" |
-m |
--delete-untagged |
"delete manifests that are not currently referenced via tag" |
-d |
--dry-run |
"do everything except remove the blobs" |
The serve command has no options.
Proposal
Introduce a new top-level command (alongside garbage-collect and serve) named database.
| Name | Description |
|---|---|
database |
"manages the registry metadata database" |
This command should have two sub-commands, named import and migrate:
| Name | Description |
|---|---|
import |
"import filesystem metadata into the database" |
migrate |
"manage database migrations" |
import
The import sub-command should support the following flags:
| Short | Long | Description |
|---|---|---|
-d |
--dry-run |
"do not commit changes to the database" |
Example: registry database import -d
migrate
This is related to #97 (closed). We want to provide a similar set of operations as those provided by Gitaly Preafect (described here) but better aligned with the style of the existing registry CLI.
The migrate sub-command should support the following sub-commands:
| Name | Description |
|---|---|
up |
"apply up migrations" |
down |
"apply down migrations" |
status |
"show migration status" |
version |
"show current migration version" |
new |
"create new migration" |
up and down
These sub-commands should support the following flags:
| Short | Long | Description |
|---|---|---|
-n |
--limit |
"limit the number of migrations to apply (all by default)" |
-d |
--dry-run |
"do not commit changes to the database" |
Example: registry database migrate up -n 10 (apply up to 10 "up" database migrations)
status
This command has no flags and the output is a table formatted list of migrations, describing if/when they were applied and if any is unknown (this can happen when the user is running an outdated registry binary that is not aware of more recent migrations).
Example output:
$ registry database migrate status
----------------------------------------------------- -------------------------------------
MIGRATION APPLIED
----------------------------------------------------- -------------------------------------
20200319122755_create_repositories_table 2020-07-03 16:29:12.740001 +0100 WEST
20200319130108_create_manifests_table 2020-07-03 16:29:12.744647 +0100 WEST
20200319131222_create_manifest_configurations_table 2020-07-03 16:29:12.750541 +0100 WEST
20200319131542_create_layers_table 2020-07-03 16:29:12.762333 +0100 WEST
20200319131632_create_manifest_layers_table 2020-07-03 16:29:12.768078 +0100 WEST
20200319131907_create_manifest_lists_table 2020-07-03 16:29:12.774065 +0100 WEST
20200319132010_create_manifest_list_items_table unknown migration
20200319132010_create_manifest_list_manifests_table no
20200319132237_create_tags_table 2020-07-03 16:29:12.80224 +0100 WEST
20200408192311_create_repository_manifests_table 2020-07-03 16:29:12.808793 +0100 WEST
20200408193126_create_repository_manifest_lists_table 2020-07-03 16:29:12.815467 +0100 WEST
20200527132906_create_repository_layers_table 2020-07-03 16:29:12.822249 +0100 WEST
version
This simply outputs the current migration version. Example:
$ registry database migrate version
20200527132906_create_repository_layers_table
new
This command will create a new empty migration based on a predefined template that the developer should fill in. This is intended for developers only.