Skip to main content

Using the Data Package Storage

If you need to apply the same SQL dump to dev, staging, and prod in turn, or just want to park an external dump in KIOPS for later, use the Data Package storage. Think of upload as putting a USB stick on a shelf, apply as carrying that USB to another computer and copying it out, and download as taking the USB back off the shelf.

This guide walks through three concrete scenarios you can follow in order.

Before You Start: Terms to Know​

  • Data package: A SQL dump bundle stored inside KIOPS together with upload time, application history, and DB type.
  • import kind: A package created by uploading a SQL dump file you have.
  • export kind: A package KIOPS itself produced by dumping a source DB (when the feature is enabled).
  • Status tags: The current state of a package - one of ready / applying / applied / failed / deleted.
  • Package apply dialog: The dialog that opens when you replay a stored package against a target DB.
  • 5GB quota / 30-day auto-clean: The operational limits applied to data packages (details in the Prerequisites section).

Prerequisites​

Before you start, the following must be in place.

  • The Data Package tab requires the Database Management permission.
  • To apply a package, the target DB must be registered under DB Connections and you must know the target / SSH / Jump passwords up front.
  • At upload time, your organization storage must be within the 5GB quota. Uploads and auto-saving are rejected once the quota is exceeded.

Location and layout of the Data Package tab​

Open it by selecting the Data Package tab among the tabs at the top of the [Database Management] page. The tabs are listed as DB Connections, Sync Jobs, Migration, Backup Management, Data Package, and Execution History, but the Sync Jobs and Migration tabs may be hidden depending on permissions — so do not look for a "Nth tab", find the Data Package label directly.

The list table has these columns.

ColumnDescription
NameDisplay name (falls back to the file name when no name is set at upload) + file name
DB typePostgreSQL / MySQL / MariaDB
SizeFile size
Statusready / applying / applied / failed / deleted
CreatedRegistration timestamp
ActionsApply / Download / Delete action buttons

Note: A package stores an import/export distinction (package_type) internally, but it is not shown as a separate "Kind" column in the list table.

The status tag uses these colors.

  • ready (gray) - Ready to apply
  • applying (blue) - Currently being applied to some target DB
  • applied (blue) - Successfully applied
  • failed (red) - Errored during application
  • deleted (gray) - Marked as deleted

The top right of the tab has an Upload SQL File button. It saves a dump file you have into the storage only (no immediate apply). The list refreshes automatically without a separate refresh button — it loads on tab entry, and auto-refreshes every 5 seconds whenever a package is in the "applying" state.

Each package row's Actions column has 3 action buttons: Apply / Download / Delete.

Quota and auto-cleanup — Total storage per organization is capped at 5GB, and uploads are rejected once the cap is hit. Packages that are in applied status and of import kind are auto-cleaned — file and list entry — 30 days after they were applied (packages merely kept in ready status are not affected). For long-term retention, download them locally.

Scenario 1. Park an externally received dump for later​

Use this flow when you have a dump you may need later but do not want to apply right now.

Step 1. Enter the Package tab​

  1. Go to [Database Management] > Data Package tab.
  2. Click the Upload SQL File button (upload icon) in the upper right.

Step 2. Pick a file and upload​

  1. Select a .sql or .sql.gz file (1GB limit).
  2. When the upload finishes, a new row appears at the top of the list with state ready.
  3. Kind is auto-classified as import, and the display name defaults to the uploaded file name.

At this point the package is "just stored" - it is not applied to any target DB. Continue to Scenario 2 when you need to apply it.

Scenario 2. Apply the same dump to multiple environments​

Use this flow when a single registered package must be rolled through dev → staging → prod. You no longer have to re-upload the file each time.

Step 1. Open the apply modal​

  1. On the Data Package tab, locate the package row to apply.
  2. Click the Apply button (lightning icon) in the Actions column.
  3. The package apply dialog opens.

The Apply button is disabled on an applying row (another job is running) — track progress via the status tag and wait for it to finish. deleted rows cannot be applied or downloaded either.

Step 2. Choose target DB and import mode​

  1. Target DB: Pick the DB connection for the environment you are rolling out to (dev / staging / prod).
  2. Import mode:
    • Append (new import) (default): Adds on top of existing data.
    • Replace (wipe and refill): Drops all tables/data in the target and refills it. Because this is dangerous, the user must select it explicitly; when chosen, the pre-apply backup option is automatically turned on and locked, and applying triggers a double confirmation (checkbox + "Apply at my own risk") acknowledging the data-loss risk.

Step 3. Enter passwords and start​

  1. Enter target DB / SSH / Jump passwords.
  2. Click Start Apply. The modal closes and the background job begins.
  3. The package row's status moves to applying (blue) and ends as applied (blue) or failed (red).

Step 4. Roll into the next environment​

A package in applied state can be re-applied. Click Apply on the same row again to roll out staging → prod, and so on.

Scenario 3. Carry a package out of KIOPS (download)​

Use this flow when you need to ship a stored dump out of KIOPS to an external server, another KIOPS instance, or a backup disk.

Step 1. Click Download​

  1. On the Data Package tab, locate the package row to take out.
  2. Click the Download button (download icon) in the Actions column.
  3. The browser starts downloading the stored .sql file. Files uploaded as .sql.gz are decompressed and kept as .sql by KIOPS, so the download is always a plain .sql.

Step 2. External storage or transfer​

  • The downloaded file can be handed to an external backup system, another KIOPS instance, or a partner as-is.
  • On a different KIOPS instance, re-upload it from the Data Package tab to replay the same dump there.

Cleaning Up Packages​

When a package is no longer needed you can remove it directly.

  1. Click the Delete button (delete icon) on the row to remove.
  2. Approve the confirmation popup.
  3. The status moves to deleted and apply / download actions become disabled.

Since auto-cleanup only targets import packages in applied status, delete ready-only stored packages or packages you no longer need yourself to keep your organization's 5GB quota usable.

Common Pitfalls​

  • Clicking Apply on an applying or deleted row: applying means another job is running — wait for it to finish. The Apply button is disabled in both applying and deleted states, and deleted rows cannot be downloaded.
  • A replace failing mid-way on production: A failed replace on production can leave you with empty tables. Always take a backup from the Backup Management tab before applying to production, and rehearse the same package on staging when possible.
  • Panicking when a package disappears due to auto-cleanup: import packages in applied status are auto-cleaned 30 days after they were applied. To keep an already-applied dump long-term, download it before the cleanup (re-uploading the same file registers it as a new package).

What to Do Next​