Merge pull request #9227 from dokku/datastore-plugin

Ship every datastore as a core datastore plugin
This commit is contained in:
Jose Diaz-Gonzalez authored and GitHub committed 2026-10-30 17:56:11 -04:00
commit a3c31275a2
47 files changed
+736 -43

No files matched your search

+1 -1
View File
@@ -190,7 +190,7 @@ Available flags:
The following flags surface in `builds:report` but are not managed by `builds:set` - they are derived metadata recorded during the build:
| Flag | Description |
|---|---|
| --- | --- |
| `--build-id` | Unique identifier of the most recent build for the app |
| `--build-kind` | Whether the record was a `build` or a `deploy` |
| `--build-status` | Display status (`running`, `succeeded`, `failed`, `canceled`, `abandoned`); computed at read time |
+127
View File
@@ -0,0 +1,127 @@
# Datastore Management
```
datastore:app-links <datastore-type> [<app>] # list all datastore service links for a given app
datastore:backup <datastore-type> <service> <bucket-name> [--id <id>]... # create a backup of the datastore service to an existing s3 bucket
datastore:backup-auth <datastore-type> <service> <aws-access-key-id> <aws-secret-access-key>... # set up authentication for backups on the datastore service
datastore:backup-deauth <datastore-type> <service> [--id <id>] # remove backup authentication for the datastore service
datastore:backup-logs <datastore-type> <service> [-t|--tail [<tail-num>]] # print the most recent output of the scheduled backups of the service
datastore:backup-schedule <datastore-type> <service> <schedule> <bucket-name>... # schedule a backup of the datastore service
datastore:backup-schedule-cat <datastore-type> <service> [--id <id>] # cat the crontab line of a scheduled backup for the service
datastore:backup-set-encryption <datastore-type> <service> <passphrase> [--id <id>] # set encryption for all future backups of datastore service
datastore:backup-set-public-key-encryption <datastore-type> <service> <public-key-id> [--id <id>] # set GPG Public Key encryption for all future backups of datastore service
datastore:backup-unschedule <datastore-type> <service> [--id <id>|--all] # unschedule the backup of the datastore service
datastore:backup-unset-encryption <datastore-type> <service> [--id <id>] # unset encryption for future backups of the datastore service
datastore:backup-unset-public-key-encryption <datastore-type> <service> [--id <id>] # unset GPG Public Key encryption for future backups of the datastore service
datastore:clone <datastore-type> <service> <new-service> [--clone-flags...] # create container <new-name> then copy data from <name> into <new-name>
datastore:connect <datastore-type> <service> # connect to the service via the <datastore-type> connection tool
datastore:create <datastore-type> <service> [--create-flags...] # create a datastore service
datastore:create-database <datastore-type> <service> <database> # create a database in the datastore service
datastore:create-user <datastore-type> <service> <user> [<password>] # create a user in the datastore service
datastore:destroy <datastore-type> <service> [-f|--force] # delete the datastore service/data/container if there are no links left
datastore:destroy-database <datastore-type> <service> <database> [-f|--force] # destroy a database created in the datastore service
datastore:destroy-user <datastore-type> <service> <user> [-f|--force] # destroy a user created in the datastore service
datastore:enter <datastore-type> <service> # enter or run a command in a running datastore service container
datastore:exists <datastore-type> <service> # check if the datastore service exists
datastore:export <datastore-type> <service> [-f|--file <path>] [--force] # export a dump of the datastore service database
datastore:expose <datastore-type> <service> <ports...> # expose a datastore service on custom host:port if provided (random port on the 0.0.0.0 interface if otherwise unspecified)
datastore:help [<datastore-type> [<command>]] # print the help for every datastore, one datastore or one of its commands
datastore:import <datastore-type> <service> [-f|--file <path>] # import a dump into the datastore service database
datastore:info <datastore-type> [<service>] [--info-flags...] # print the service information
datastore:label <datastore-type> <service> <key=value>... # add docker labels to the service container
datastore:link <datastore-type> <service> [<app>] [--link-flags...] # link the datastore service to the app
datastore:linked <datastore-type> <service> [<app>] # check if the datastore service is linked to an app
datastore:links <datastore-type> <service> # list all apps linked to the datastore service
datastore:list <datastore-type> # list all datastore services
datastore:logs <datastore-type> <service> [-t|--tail [<tail-num>]] # print the most recent log(s) for this service
datastore:mount <datastore-type> [--replace] <service> <source:container-dir[:options]>... # mount a host path or docker volume into the service container
datastore:pause <datastore-type> <service> # pause a running datastore service
datastore:promote <datastore-type> <service> [<app>] # promote service <service> as DATABASE_URL in <app>
datastore:reexpose <datastore-type> <service> # reexpose a datastore service, applying its expose settings
datastore:reset <datastore-type> <service> [-f|--force] # delete all data in the datastore service, keeping the service and its links
datastore:restart <datastore-type> <service> # graceful shutdown and restart of the datastore service container
datastore:set <datastore-type> <service> <key> [<value>]... # set or clear a property for a service
datastore:set-user-password <datastore-type> <service> <user> [<password>]... # change the password of a user created in the datastore service
datastore:start <datastore-type> <service> # start a previously stopped datastore service
datastore:stop <datastore-type> <service> # stop a running datastore service
datastore:unexpose <datastore-type> <service> # unexpose a previously exposed datastore service
datastore:unlabel <datastore-type> [--all] <service> [<key>...] # remove one or all docker labels from the service container
datastore:unlink <datastore-type> <service> [<app>] [-n|--no-restart] # unlink the datastore service from the app
datastore:unmount <datastore-type> [--all] <service> [<source:container-dir>...] # remove one or all mounts from the service container
datastore:upgrade <datastore-type> <service> [--upgrade-flags...] # upgrade service <service> to the specified versions
datastore:version # print the version of dokku-datastore the plugin runs
```
The `datastore` plugin manages datastore services such as postgres, mysql and redis, and links them to apps. Every command takes the datastore type as its first argument, and the datastores it serves are the ones the [official datastore plugins](/docs/community/plugins.md#official-plugins) provide: clickhouse, couchdb, elasticsearch, graphite, mariadb, meilisearch, memcached, mongo, mysql, nats, omnisci, postgres, pushpin, rabbitmq, redis, rethinkdb, solr and typesense.
The plugin is built from [dokku-datastore](https://github.com/dokku/dokku-datastore), which the official datastore plugins also run, and keeps its services in the same place they do, under `/var/lib/dokku/services`.
## Usage
### Creating and linking a service
A service is created with `datastore:create` and linked to an app with `datastore:link`, which sets the variable the app connects with, such as `DATABASE_URL` for postgres or `REDIS_URL` for redis, and restarts the app.
```shell
dokku datastore:create postgres lollipop
dokku datastore:link postgres lollipop node-js-app
```
`datastore:unlink` removes the link, and `datastore:destroy` removes a service once nothing is linked to it.
```shell
dokku datastore:unlink postgres lollipop node-js-app
dokku datastore:destroy postgres lollipop
```
Deleting an app unlinks it from every service it is linked to.
### Getting help
`datastore:help` lists the datastore types and the commands they share. Not every datastore implements every command, so the help for one datastore lists only the commands it implements, including ones only it has, such as `connect-admin` for mongo. The help for one of a datastore's commands describes its flags and shows examples.
```shell
dokku datastore:help
dokku datastore:help postgres
dokku datastore:help postgres create
```
### Scheduled backups
A backup scheduled with `datastore:backup-schedule` is added to the dokku crontab as a `dokku datastore:backup` command, and is managed with the [cron plugin](/docs/processes/scheduled-cron-tasks.md) like any other scheduled task.
```shell
dokku datastore:backup-auth postgres lollipop AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY
dokku datastore:backup-schedule postgres lollipop "0 3 * * *" my-s3-bucket
```
### Images
Installing dokku does not pull the image of every datastore. A datastore's images are pulled the first time a command needs them, and on later installs and upgrades once the datastore has a service.
### Official datastore plugins
The official datastore plugins, such as [dokku-postgres](https://github.com/dokku/dokku-postgres), may be installed alongside the `datastore` plugin. While one is enabled, the `datastore` plugin leaves that datastore to it when dokku runs plugin triggers, such as unlinking an app that is being deleted or writing scheduled backups into the crontab. Commands for that datastore should be run through the official plugin until it is removed.
The `datastore` plugin does not read the datastore definitions an official plugin ships, so a host running a modified official plugin should keep using it.
#### Migrating from an official datastore plugin
Moving a datastore from its official plugin to the `datastore` plugin leaves its services, containers, data, settings and links where they are, and does not stop running services or the apps linked to them. Using postgres as an example:
1. Check that `dokku datastore:version` is at least the version dokku-postgres runs, which is printed by `/var/lib/dokku/data/postgres/dokku-datastore version`. If the official plugin runs a newer version, wait for a dokku release that ships it.
2. Uninstall the official plugin.
```shell
dokku plugin:uninstall postgres
```
3. Run every plugin's install trigger, which sets the host up for postgres, brings its services up to date and rewrites the crontab so scheduled backups run through `dokku datastore:backup`.
```shell
dokku plugin:install
```
4. Change anything that runs `dokku postgres:<command> <service>` to run `dokku datastore:<command> postgres <service>`.
To move back, install the official plugin again from a release running at least the version `dokku datastore:version` prints.
+1 -1
View File
@@ -142,7 +142,7 @@ app2.json
#### `app.json` deployment tasks
Dokku provides limited support for the `app.json` manifest from Heroku (documentation available [here](https://devcenter.heroku.com/articles/app-json-schema)). The keys available for use with Deployment Tasks are:
Dokku provides limited support for the `app.json` manifest from Heroku (see the [app.json schema documentation](https://devcenter.heroku.com/articles/app-json-schema)). The keys available for use with Deployment Tasks are:
- `scripts.dokku.predeploy`: This is run _after_ an app's docker image is built, but _before_ any containers are scheduled. Changes made to your image are committed at this phase.
- `scripts.dokku.postdeploy`: This is run _after_ an app's containers are scheduled. Changes made to your image are _not_ committed at this phase.
+2 -2
View File
@@ -34,7 +34,7 @@ Adding or removing docker-options will not apply to any running containers, and
#### Supported Docker Options
More information on supported Docker options can be found [here](https://docs.docker.com/engine/reference/commandline/run/).
More information on supported Docker options can be found in the [docker run reference](https://docs.docker.com/engine/reference/commandline/run/).
Container options configured via the `docker-options` plugin are not used to modify the process a container runs. Container options are the `[OPTIONS]` portion of the following, where `[CONTAINER_COMMAND]` and `[ARG]` are the process and the arguments passed to it that are launched in the created container: `docker run [OPTIONS] [CONTAINER_COMMAND] [ARG...]`. Please see the documentation for [customizing the run command](/docs/deployment/builders/dockerfiles.md#customizing-the-run-command) or use a [Procfile](/docs/deployment/builders/dockerfiles.md#procfiles-and-multiple-processes) to modify the command used by a Dockerfile-based container.
@@ -288,7 +288,7 @@ dokku docker-options:list node-js-app --phase deploy
The following properties are recorded internally by the docker-options plugin and are not exposed via `docker-options:report`:
| Property | Scope | Description | Source |
|---|---|---|---|
| --- | --- | --- | --- |
| `migrated-from-files` | global | Global migration sentinel that records that the legacy `DOCKER_OPTIONS_<PHASE>` flat-file store has been drained into plugin properties | `plugins/docker-options/functions.go` writes `"true"` once the install-time migration runs |
| `migrated-build` | per-app | Per-app marker recording that the app's legacy `DOCKER_OPTIONS_BUILD` file was drained into the `_default_.build` property list. Only set when the legacy file contained non-empty content | `plugins/docker-options/functions.go` writes `"true"` after the per-phase drain |
| `migrated-deploy` | per-app | Per-app marker recording that the app's legacy `DOCKER_OPTIONS_DEPLOY` file was drained into the `_default_.deploy` property list. Only set when the legacy file contained non-empty content | `plugins/docker-options/functions.go` writes `"true"` after the per-phase drain |
+2 -2
View File
@@ -172,7 +172,7 @@ dokku storage:set node-js-data chown
The following properties can be set:
| Property | Description | Unsetting it means |
|---|---|---|
| --- | --- | --- |
| `chown` | Ownership preset or numeric uid for the host directory | no chown is performed |
| `mode` | Octal permissions for the host directory | permissions are left alone |
| `namespace` | Namespace holding the PVC (k3s) | the `default` namespace |
@@ -324,7 +324,7 @@ dokku storage:mount --replace node-js-app \
```
| Token | Meaning |
|---|---|
| --- | --- |
| `ro` | Mount the volume read-only |
| `rw` | Mount it read-write, the explicit opposite of `ro` and the default |
| `volume-subpath=<path>` | Subpath within the entry |
+2 -2
View File
@@ -283,7 +283,7 @@ dokku registry:set --global push-extra-tags
> The `Report flags` column lists the CLI argument names accepted by `registry:report`. The JSON keys emitted by `registry:report --format json` are the same names with the leading `--registry-` stripped (e.g. `image-repo`, `global-server`, `computed-push-on-release`). Legacy keys with the `registry-` prefix (e.g. `registry-image-repo`) are also emitted during the 0.38.x deprecation window and will be removed in a future major release.
| Property | Scope | Default | Report flags | Description |
|---|---|---|---|---|
| --- | --- | --- | --- | --- |
| `image-repo` | app only | `dokku/<app>` | `--registry-image-repo`, `--registry-computed-image-repo` | Repository name used when pushing the app's image (overrides the global template) |
| `image-repo-template` | app + global | none | `--registry-image-repo-template`, `--registry-global-image-repo-template`, `--registry-computed-image-repo-template` | Go template used to compute the per-app image repository when `image-repo` is unset |
| `push-extra-tags` | app + global | none | `--registry-push-extra-tags`, `--registry-global-push-extra-tags`, `--registry-computed-push-extra-tags` | Comma-separated list of additional tags pushed alongside the deploy tag |
@@ -298,7 +298,7 @@ dokku registry:set --global push-extra-tags
The following `registry:report` fields describe credentials created by `registry:login` and are not settable via `registry:set`.
| Report flag | Scope | Description |
|---|---|---|
| --- | --- | --- |
| `--registry-auth-servers` | app only | Comma-separated list of servers the app has its own credentials for |
| `--registry-global-auth-servers` | app + global | Comma-separated list of servers the global credentials cover |
| `--registry-computed-auth-servers` | app + global | Comma-separated list of servers whose credentials would be used for the app |