Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Migration

This page describes the process of migrating data into fylr instances using the /inspect/migration page in fylr

The migration using the fylr backup and fylr restore commands can also be performed in the inspect page for migrations (open <fylr url>/inspect/migration/ in the browser). This provides a graphical overview to run these commands.

The source instance for the backup can be any easydb5 or fylr instance, even the current fylr instance. The same is true for the target instance of the restore, this can be the same fylr instance.

The following example shows how a backup with the name "example" would be migrated from server "http://example.fylr.xyz" to server "http://target.fylr.xyz".

The backup and restore processes are performed in the background. They run on the server and are independent of the browser window. The progress can be checked by opening the status page of a backup / restore process (see below).

Backup

This uses fylr backup to create a backup on the fylr instance. Not all parameters can be set here. Some parameters are automatically set with a useful default.

See also: Backup Parameters

Parameter settings

Name of backup

  • choose a name to identify the backup

  • This sets --dir example/

URL of server

  • URL of the source server without API base endpoint

  • This sets --server 'http://example.fylr.xyz/api/v1/'

Login

  • Username in the source instance

  • This sets --login root

Password

  • Password in the source instance

  • This sets --password '12345'

Backup chunk size

  • Select the batch size for GET requests

  • Choose between: 10, 25, 50, 100, 500, 1000

  • This sets --chunk

Include object history

  • If set, the backup will include all versions of an object

  • With this option, the full changelog of an object will be available after restore

  • This option is enabled by default

  • This sets --all-versions true

Include soft-deleted objects

This parameter is available in fylr from version 6.33.0.

  • If set, objects that are soft-deleted in the source are included in the backup as top-level entries (in their soft-deleted state)

  • Links pointing at soft-deleted targets are always written to the backup as a lookup:_id wrapper carrying _latest_version_deleted_at; this option only controls whether the target object itself rides along

  • Pair with the restore-side "Include links to soft-deleted objects" for a faithful round-trip

  • This sets --include-deleted true

Include events

  • If set, all events from the source are included in the backup

  • If not set, the backup of events is skipped

  • This sets --include-events

Include Files

This parameter is available in fylr from version 6.34.0.

  • A selector controlling how file bytes are stored in the backup:

    • URLs only (do not pack) — only the file URLs are stored; the bytes are fetched from the source during the restore, so the source must stay reachable

    • Originals — pack each file's original bytes into the backup directory (files/<id>/…), making the backup self-contained and byte-for-byte; renditions are regenerated on the target during the restore

    • Originals + versions — also pack the renditions, so that a restore with Copy file preview versions uploads them from the backup byte-identical instead of regenerating them

  • Files kept on the remote (leave) are never packed; their real upstream URL is preserved instead

  • This sets --include-files

OAuth2

  • Select only if the source instance uses OAuth2

  • easydb5 does not use OAuth2

  • this enables the following options:

    • OAuth2 Client Id

      • Client Id of the source instance

      • This sets --client-id fylr-web-frontend

    • OAuth2 Client Secret

      • Client Secret of the source instance

      • Leave empty if the source instance is public

      • This sets --client-secret foo

Allow Insecure Connection

This parameter is available in fylr from version v6.14.0.

  • If set, the certificate check for the connection to the source instance is skipped

Only use this option if you can trust the remote server!

Purge or Continue

  • Purge

    • The existing backup folder is purged and a new backup process is started

    • This sets --purge

  • Continue

    • A previous backup process is continued

    • This sets --continue

Fixed parameters

The following parameters are set in the background:

Progress

Click on Backup to start the backup process in the background. To see the progress of the backup, select the backup in the overview List of backups. This opens a page where you can see the status and the backup log. The generated payloads are listed under the log. When the backup was made with Include Files, the packed files/ directory is shown here too — click into the nested folders to browse the stored file bytes.

You can also access this page directly under <fylr url>/inspect/migration/<backup name>, so in this example under <fylr url>/inspect/migration/example.

Restore

After a backup was finished, it can be restored to a target fylr instance.

This uses fylr restore to upload the payloads to the fylr instance. Not all parameters can be set here. Some parameters are automatically set with a useful default.

See also: Restore Parameters

Parameter settings

Backup

  • Select one of the backups

  • This sets --manifest 'example/manifest.json'

URL

  • URL of the target server without API base endpoint

  • This sets --server 'http://target.fylr.xyz/api/v1/'

Login

  • Username in the target instance

  • This sets --login root

Password

  • Password in the target instance

  • This sets --password '12345'

File Mode

  • Method used to upload files, leave empty to not upload files (this is the default)

    • Copy files from source (through browser) - put

    • Copy files from source (via server) - rput

    • Use files from source - rput_leave

      • The target server stores remote URLs, no data is copied to storage

      • Use rput_leave to not copy files to the restored instance if you want to only test a migration quickly

  • This sets --file-api rput

File Version

  • Set a version which will be used as the new original version in the restored instance

    • original (the original asset, no version. This is the default)

    • preview

    • and other version names (depend on configurations)

  • If you are not using rput_leave use a small version like preview to save disk space and process more quickly

  • This sets --file-version original

Copy file preview versions

  • Enable this checkbox to not produce local preview versions, but instead copy the source versions (via put or rput)

  • If you are using rput_leave, the source version is linked as URL

  • This sets --upload-versions

When you restore a backup that was made with Include Files, the packed original bytes are uploaded from the local backup directory automatically. Renditions still follow Copy file preview versions: enable it to upload them (from the backup if it was made with Originals + versions, otherwise from the source), leave it off to have the target regenerate them. For an Originals-only backup Copy file preview versions cannot be used — the renditions are not packed.

Rename Versions

This parameter is available in fylr from version 6.33.0.

  • Rename file versions (renditions) as objects are uploaded into the target instance — useful when the source uses different version names than the target (e.g. video.1920p → 1080p)

  • The form shows a table with three columns: File class, Source version, Target version; a new empty row is appended automatically as soon as the last one is filled

  • Leave Target version empty to remove the version on the target

  • When a backup is selected, the table is pre-populated from the restore parameters used on the previous run

  • On submit, the rows are serialized into --rename-versions <cls>.<version>:<new version>,...

See: renaming renditions during migration

Access Token for file URLs

This is only needed if the source instance of the backup is a fylr and there are files that should be uploaded to the target instance. fylr requires all requests to be authenticated. So during the restore process the file URLs need to be accessed in the source fylr, but this will fail if there is no authentication.

During the backup, fylr adds a signature parameter to the file URLs (x-fylr-signature) which can be used to authenticate the request. But this signature is temporary and expires after a fixed time which is configured in the source instance. If you try to restore after a certain time the signatures can be expired and the source instance will not allow access to the files anymore.

To override the signature, you can get an OAuth2 Access Token from the source instance which has read rights on these files. If this token is passed, the restore tool will parse the file URLs and remove the signature parameter, and set the access_token parameter instead.

This sets --file-api-access-token <token>

Chunk size

  • Select the batch size for POST requests

  • Choose between: 10, 25, 50, 100, 500, 1000

  • This sets --chunk

Include Password

  • Enable this checkbox to include user password hashes

  • If this option is true, the restore tool checks if there is at least one user where a password hash is present

  • This sets --include-password

Include events

  • If set, all events which have an event type that is known by fylr are restored

  • This means if there are unknown events in the backup (from easydb5), these will not be imported

  • If not set, no events will be imported

  • This sets --include-events

Include links to soft-deleted objects

This parameter is available in fylr from version 6.33.0.

  • If set, link wrappers pointing at a soft-deleted target are kept in the restored object instead of being stripped

  • Only fully meaningful when the source backup was taken with "Include soft-deleted objects" — the lookup then resolves to the restored target

  • Without "Include soft-deleted objects" at backup, the lookup defers and the link surfaces as _purged_or_deferred on read (the same shape the API serves after a real purge of the target)

  • This sets --include-deleted-linked true

OAuth2

  • Select only if the target instance uses OAuth2

  • easydb5 does not use OAuth2

  • this enables the following options:

  • OAuth2 Client Id

    • Client Id of the target instance

    • This sets --client-id web-client

  • OAuth2 Client Secret

    • Client Secret of the target instance

    • Leave empty if the target instance is public

    • This sets --client-secret foo

Allow Insecure Connection

This parameter is available in fylr from version v6.14.0.

  • If set, the certificate check for the connection to the target instance is skipped

Only use this option if you can trust the remote server!

Purge or Continue

  • Purge

    • The target instance is purged and a new restore process is started

    • This uploads the base config and the data model

    • This sets --purge

  • Continue

    • A previous restore process of this backup is continued

    • This sets --continue

  • No Purge

    • Does not purge the target instance

    • Data model and base config are not uploaded

    • This mode only uploads base types and user records

    • Use this after manually purging the target and manually uploading the data model and base config

    • This sets neither --purge nor --continue, but --base-config=- and --datamodel=-

See also: Best Practice > Restoring with and without purge

Fixed parameters

The following parameters are set in the background:

Progress

Click on Restore to start the restoring process in the background.

Confirm the message This will destroy all data on "http://target.fylr.xyz"!. Be sure you want to delete all data and the complete datamodel on the target instance. The restore process is always performed with --purge.

The progress of the restore is the shown in a new page where you can see the log. You also access this page directly under <fylr url>/inspect/migration/<backup name>, so in this example under <fylr url>/inspect/migration/example.

PreviousSystemNextTerm Recalculation

Last updated