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 snapshots, 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.

The logical database can be split into multiple shards, where each shard is an independent SQL database instance holding a subset of the total data. This is used for horizontal scalability.

⚠️ 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 Snapshots

The Metaplay CLI has commands for exporting and importing database snapshots 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 snapshots are only intended for small databases, of a size of less than 1GB. Snapshots are a complement to Metaplay's built-in backup systems that can operate on terabyte scales in production.

You can export a database snapshot using the Metaplay CLI:

metaplay database export-snapshot [ENVIRONMENT] [FILENAME]

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

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

metaplay database import-snapshot [ENVIRONMENT] [FILENAME]

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

Further Reading

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