Dependencies

• An active cloud environment - You need to have a project with a cloud environment to interact with its database.
• Access to the Metaplay CLI - You need to have the Metaplay CLI installed.

Overview

This guide covers common operations on the database, such as how to reset the database of a cloud environment or the local server on your machine. It also covers how to export and import database archives, for example, to copy the database state from one development environment to another.

Metaplay uses different types of databases, depending on where you're running the game server:

• For locally running game servers, the logical database is stored in SQLite files.
• For cloud development environments, in-cluster MariaDB pods are used.
• For cloud staging and production environments, auto-scaling Aurora MySQL Serverless clusters are used.

Only for Staging and Production Environments

In staging and production environments, the logical database may be partitioned into multiple shards. Each shard operates as an independent SQL database instance, containing a portion of the overall data. This sharding architecture enables horizontal scalability and is not supported in local or development environments.

⚠️ Shut Down the Game Server First

Always stop the game server before performing operations on a local or cloud database. Otherwise, you risk the database ending up in an inconsistent state. You can stop the cloud game server with metaplay remove server [ENVIRONMENT].

Reset a Local Database

You can reset the database of the locally running game server simply by deleting the database shard SQLite files:

MyProject$ rm -f Backend/Server/bin/Shardy*.db

This will reset the database to its initial state, deleting all data stored in the database.

Reset a Database in the Cloud

You can reset the database of a cloud environment using the Metaplay CLI:

metaplay database reset [ENVIRONMENT]

This will reset the database of the specified environment to its initial state, deleting all data stored in the database.

Cloud Database Archives

The Metaplay CLI has commands for exporting and importing database archives to and from your local file system. They can be useful for migrating the database state between two development environments, or for ad hoc backup and restore operations.

The database archives are only intended for small databases, of a size of less than 1GB. Archives are a complement to Metaplay's built-in backup systems that can operate on terabyte scales in production.

You can export a database archive using the Metaplay CLI:

metaplay database export-archive [ENVIRONMENT] [FILENAME]

This will output an archive file with the database state included. The archive contains metadata about the archive, the schema for the database, and the data from each of the database shards.

You can import this archive into an environment (either the same or a different one) using the Metaplay CLI:

metaplay database import-archive [ENVIRONMENT] [FILENAME]

This will import the archive into the specified environment, overwriting the existing database state.

Further Reading

Check out the Working with the Database page for information on how to programmatically access the database from your game server.