diff --git a/docs/docs/docs/01-core/data-transfer/03-local-strapi-providers/00-overview.md b/docs/docs/docs/01-core/data-transfer/03-local-strapi-providers/00-overview.md index ccc1428f00..b9aae79419 100644 --- a/docs/docs/docs/01-core/data-transfer/03-local-strapi-providers/00-overview.md +++ b/docs/docs/docs/01-core/data-transfer/03-local-strapi-providers/00-overview.md @@ -1,5 +1,5 @@ --- -title: File Providers +title: Local Strapi Providers tags: - experimental - providers @@ -8,6 +8,10 @@ tags: - data-transfer --- -# Strapi Data File Providers +# Local Strapi Providers -**TODO** +The local Strapi provider allows using the local Strapi instance (the same project that the data transfer engine is being run from) as a data source. + +Creating a local Strapi data provider requires passing in an initialized `strapi` server object to interact with that server's Entity Service and Query Engine to manage the data. Therefore if the local Strapi project cannot be started (due to errors), the providers cannot be used. + +**Important**: When a transfer completes, the `strapi` object passed in is shut down automatically based on the `autoDestroy` option. If you are running a transfer via an external script, it is recommended to use `autoDestroy: true` to ensure it is shut down properly, but if you are running a transfer within a currently running Strapi instance you should set `autoDestroy: false` or your Strapi instance will be shut down at the end of the transfer. diff --git a/docs/docs/docs/01-core/data-transfer/03-local-strapi-providers/01-source.md b/docs/docs/docs/01-core/data-transfer/03-local-strapi-providers/01-source.md new file mode 100644 index 0000000000..84104c86a1 --- /dev/null +++ b/docs/docs/docs/01-core/data-transfer/03-local-strapi-providers/01-source.md @@ -0,0 +1,21 @@ +--- +title: Local Strapi Source +tags: + - providers + - data-transfer + - experimental +--- + +# Local Strapi Source Provider + +This provider will retrieve data from an initialized `strapi` instance using its Entity Service and Query Engine. + +## Provider Options + +The accepted options are defined in `ILocalFileSourceProviderOptions`. + +```typescript + getStrapi(): Strapi.Strapi | Promise; // return an initialized instance of Strapi + + autoDestroy?: boolean; // shut down the instance returned by getStrapi() at the end of the transfer +``` diff --git a/docs/docs/docs/01-core/data-transfer/03-local-strapi-providers/02-destination.md b/docs/docs/docs/01-core/data-transfer/03-local-strapi-providers/02-destination.md new file mode 100644 index 0000000000..e4d79e6eb9 --- /dev/null +++ b/docs/docs/docs/01-core/data-transfer/03-local-strapi-providers/02-destination.md @@ -0,0 +1,56 @@ +--- +title: Local Strapi Destination +tags: + - providers + - data-transfer + - experimental +--- + +# Local Strapi Destination Provider + +This provider will insert data into an initialized `strapi` instance using its Entity Service and Query Engine. + +## Provider Options + +The accepted options are defined in `ILocalFileSourceProviderOptions`. + +```typescript + getStrapi(): Strapi.Strapi | Promise; // return an initialized instance of Strapi + autoDestroy?: boolean; // shut down the instance returned by getStrapi() at the end of the transfer + restore?: restore.IRestoreOptions; // the options to use when strategy is 'restore' + strategy: 'restore'; // conflict management strategy; only the restore strategy is available at this time +``` + +`strategy` defines the conflict management strategy used. Currently, only `"restore"` is available as an option. + +### Restore + +A conflict management strategy of "restore" deletes all existing Strapi data before a transfer to avoid any conflicts. + +The following restore options are available: + +```typecript +export interface IRestoreOptions { + assets?: boolean; // delete media library files before transfer + configuration?: { + webhook?: boolean; // delete webhooks before transfer + coreStore?: boolean; // delete core store before transfer + }; + entities?: { + include?: string[]; // only delete these stage entities before transfer + exclude?: string[]; // exclude these stage entities from deletion + filters?: ((contentType: ContentTypeSchema) => boolean)[]; // custom filters to exclude a content type from deletion + params?: { [uid: string]: unknown }; // params object passed to deleteMany before transfer for custom deletions + }; +} +``` + +### Rollbacks + +This local Strapi destination provider automatically provides a rollback mechanism on error. + +For Strapi data, that is done with a database transaction wrapped around the restore and the insertion of data and committing on succes and rolling back on failure. + +For Strapi assets (ie, the media library files) this is done by attempting to temporarily move the existing assets to a backup directory to `uploads_backup_{timestamp}`, and then deleting it on success, or deleting the failed import files and putting the backup back into place on failure. In some cases of failure, it may be impossible to move the backup files back into place, so you will need to manually restore the backup assets files. + +Note: Because of the need for write access, environments without filesystem permissions to move the assets folder (common for virtual environments where /uploads is mounted as a read-only drive) will be unable to include assets in a transfer and the asset stage must be excluded in order to run the transfer. diff --git a/docs/docs/docs/01-core/data-transfer/03-local-strapi-providers/02-source.md b/docs/docs/docs/01-core/data-transfer/03-local-strapi-providers/02-source.md deleted file mode 100644 index 2b664c07ed..0000000000 --- a/docs/docs/docs/01-core/data-transfer/03-local-strapi-providers/02-source.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Strapi File -tags: - - providers - - data-transfer - - experimental ---- - -# Strapi File Source Provider - -This provider will output a Strapi Data File - -**TODO** diff --git a/docs/docs/docs/01-core/data-transfer/03-local-strapi-providers/03-destination.md b/docs/docs/docs/01-core/data-transfer/03-local-strapi-providers/03-destination.md deleted file mode 100644 index 9398ac4053..0000000000 --- a/docs/docs/docs/01-core/data-transfer/03-local-strapi-providers/03-destination.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Strapi File -tags: - - providers - - data-transfer - - experimental ---- - -# Strapi File Destination Provider - -This provider will output a Strapi Data File - -Note: this destination provider does not provide a schema or metadata, and will therefore never report a schema match error or version validation error - -**TODO** diff --git a/docs/docs/docs/01-core/data-transfer/03-local-strapi-providers/_category_.json b/docs/docs/docs/01-core/data-transfer/03-local-strapi-providers/_category_.json index 6663af8f1e..ed459a68c3 100644 --- a/docs/docs/docs/01-core/data-transfer/03-local-strapi-providers/_category_.json +++ b/docs/docs/docs/01-core/data-transfer/03-local-strapi-providers/_category_.json @@ -1,5 +1,5 @@ { - "label": "File Providers", + "label": "Local Strapi Providers", "collapsible": true, "collapsed": true } diff --git a/docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/00-overview.md b/docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/00-overview.md index ccc1428f00..70179091dd 100644 --- a/docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/00-overview.md +++ b/docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/00-overview.md @@ -1,5 +1,5 @@ --- -title: File Providers +title: Remote Strapi Providers tags: - experimental - providers @@ -8,6 +8,6 @@ tags: - data-transfer --- -# Strapi Data File Providers +# Remote Strapi Providers **TODO** diff --git a/docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/01-file-structure.md b/docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/01-file-structure.md deleted file mode 100644 index 9f838bc403..0000000000 --- a/docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/01-file-structure.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Strapi File -tags: - - providers - - data-transfer - - experimental ---- - -# Strapi File Structure - -**TODO** diff --git a/docs/docs/docs/01-core/data-transfer/03-local-strapi-providers/01-file-structure.md b/docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/01-websocket.md similarity index 54% rename from docs/docs/docs/01-core/data-transfer/03-local-strapi-providers/01-file-structure.md rename to docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/01-websocket.md index 9f838bc403..2633b566fa 100644 --- a/docs/docs/docs/01-core/data-transfer/03-local-strapi-providers/01-file-structure.md +++ b/docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/01-websocket.md @@ -1,11 +1,11 @@ --- -title: Strapi File +title: Remote Provider Websocket tags: - providers - data-transfer - experimental --- -# Strapi File Structure +# Remote Provider Websocket **TODO** diff --git a/docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/02-source.md b/docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/02-source.md index 2b664c07ed..91900819e2 100644 --- a/docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/02-source.md +++ b/docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/02-source.md @@ -1,13 +1,11 @@ --- -title: Strapi File +title: Strapi Remote Source Provider tags: - providers - data-transfer - experimental --- -# Strapi File Source Provider - -This provider will output a Strapi Data File +# Strapi Remote Source Provider **TODO** diff --git a/docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/03-destination.md b/docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/03-destination.md index 9398ac4053..8e12576612 100644 --- a/docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/03-destination.md +++ b/docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/03-destination.md @@ -1,15 +1,11 @@ --- -title: Strapi File +title: Remote Destination Provider tags: - providers - data-transfer - experimental --- -# Strapi File Destination Provider - -This provider will output a Strapi Data File - -Note: this destination provider does not provide a schema or metadata, and will therefore never report a schema match error or version validation error +# Strapi Remote Destination Provider **TODO** diff --git a/docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/_category_.json b/docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/_category_.json index 6663af8f1e..248a1e6d21 100644 --- a/docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/_category_.json +++ b/docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/_category_.json @@ -1,5 +1,5 @@ { - "label": "File Providers", + "label": "Remote Strapi Providers", "collapsible": true, "collapsed": true } diff --git a/packages/core/data-transfer/src/strapi/providers/local-destination/index.ts b/packages/core/data-transfer/src/strapi/providers/local-destination/index.ts index a5555dc3aa..64f32de30c 100644 --- a/packages/core/data-transfer/src/strapi/providers/local-destination/index.ts +++ b/packages/core/data-transfer/src/strapi/providers/local-destination/index.ts @@ -18,10 +18,11 @@ export const VALID_CONFLICT_STRATEGIES = ['restore', 'merge']; export const DEFAULT_CONFLICT_STRATEGY = 'restore'; export interface ILocalStrapiDestinationProviderOptions { - getStrapi(): Strapi.Strapi | Promise; - autoDestroy?: boolean; - restore?: restore.IRestoreOptions; - strategy: 'restore' | 'merge'; + getStrapi(): Strapi.Strapi | Promise; // return an initialized instance of Strapi + + autoDestroy?: boolean; // shut down the instance returned by getStrapi() at the end of the transfer + restore?: restore.IRestoreOptions; // erase all data in strapi database before transfer + strategy: 'restore'; // conflict management strategy; only the restore strategy is available at this time } class LocalStrapiDestinationProvider implements IDestinationProvider { diff --git a/packages/core/data-transfer/src/strapi/providers/local-destination/strategies/restore/index.ts b/packages/core/data-transfer/src/strapi/providers/local-destination/strategies/restore/index.ts index 3d4808a17c..d87787741d 100644 --- a/packages/core/data-transfer/src/strapi/providers/local-destination/strategies/restore/index.ts +++ b/packages/core/data-transfer/src/strapi/providers/local-destination/strategies/restore/index.ts @@ -3,16 +3,16 @@ import { ProviderTransferError } from '../../../../../errors/providers'; import * as queries from '../../../../queries'; export interface IRestoreOptions { - assets?: boolean; + assets?: boolean; // delete media library files before transfer configuration?: { - webhook?: boolean; - coreStore?: boolean; + webhook?: boolean; // delete webhooks before transfer + coreStore?: boolean; // delete core store before transfer }; entities?: { - include?: string[]; - exclude?: string[]; - filters?: ((contentType: ContentTypeSchema) => boolean)[]; - params?: { [uid: string]: unknown }; + include?: string[]; // only delete these stage entities before transfer + exclude?: string[]; // exclude these stage entities from deletion + filters?: ((contentType: ContentTypeSchema) => boolean)[]; // custom filters to exclude a content type from deletion + params?: { [uid: string]: unknown }; // params object passed to deleteMany before transfer for custom deletions }; } diff --git a/packages/core/data-transfer/src/strapi/providers/local-source/index.ts b/packages/core/data-transfer/src/strapi/providers/local-source/index.ts index d7f66a0bf5..0df584d313 100644 --- a/packages/core/data-transfer/src/strapi/providers/local-source/index.ts +++ b/packages/core/data-transfer/src/strapi/providers/local-source/index.ts @@ -10,9 +10,9 @@ import * as utils from '../../../utils'; import { assertValidStrapi } from '../../../utils/providers'; export interface ILocalStrapiSourceProviderOptions { - getStrapi(): Strapi.Strapi | Promise; + getStrapi(): Strapi.Strapi | Promise; // return an initialized instance of Strapi - autoDestroy?: boolean; + autoDestroy?: boolean; // shut down the instance returned by getStrapi() at the end of the transfer } export const createLocalStrapiSourceProvider = (options: ILocalStrapiSourceProviderOptions) => {