metaplay debug database [ENVIRONMENT] [SHARD] [flags] [-- EXTRA_ARGS]

Connect to a database shard for the specified environment using MariaDB CLI.

This command starts a temporary debug pod and runs an SQL client inside it, connecting to the specified database replica (read-only or read-write), and shard.

By default, the read-only replica will be used, for safety. Use --read-write to connect to the read-write replica.

Optionally, you can use --query <sql> to specify a SQL statement to execute immediately and output the result, or --query-file <filename> to read the SQL statement from a file.

When running non-interactive queries (using --query or --query-file), you can use --output <filename> to write the output to a file instead of stdout.

Expected arguments:

• ENVIRONMENT (optional) -- Target environment name or id, eg, 'lovely-wombats-build-nimbly'.
• SHARD (optional) -- Optional: Database shard index to connect to. If not specified, the first shard (index 0) will be used.
• EXTRA_ARGS (optional) -- Passed as-is to mariadb CLI.

Related commands:

• 'metaplay debug shell' starts a debug shell in a running game server pod.

Examples

# Connect to a database shard in the 'nimbly' environment using the first shard
metaplay debug database nimbly
# Connect to the second shard in the 'nimbly' environment (0-based indexing is used)
metaplay debug database nimbly 1
# Connect to the read-write replica instead of the default read-only replica
metaplay debug database nimbly --read-write
# Run a query on the first shard and exit immediately after
metaplay debug database nimbly 0 --query "SELECT COUNT(*) FROM Players"
# Run a query on the first shard and write the output to a file
metaplay debug database nimbly 0 --query "SELECT COUNT(*) FROM Players" --output count.txt
# Run a query from a file on the first shard and exit immediately after
metaplay debug database nimbly 0 --query-file ./my_query.sql
# Pass extra arguments to mariadb CLI (e.g., for formatting)
metaplay debug database nimbly 0 -- --batch --skip-column-names
# Get player entity payload as binary and write to a file
metaplay debug database nimbly 0 --query "SELECT Payload FROM Players WHERE EntityId='Player:0000000000'" -- -N -B --raw > player.bin
# Fetch multiple players into a file as JSON objects, with one player/object per line, payload encoded with base64
metaplay debug database nimbly 0 --query "SELECT json_object('EntityId', EntityId, 'Payload', to_base64(Payload)) FROM Players LIMIT 5" -- -N -B --raw > players.json

Flags

• --output <string>: Write output to a file instead of stdout (non-interactive)
• --query <string>: Run this SQL query and exit (non-interactive)
• --query-file <string>: Read SQL query from a file and execute it (non-interactive)
• --read-write: Connect to the read-write replica (default: read-only)

Inherited Flags

• --color <string>: Should the output be colored (yes/no/auto)? [env: METAPLAYCLI_COLOR] (default: auto)
• --project <string>: Path to the to project directory (where metaplay-project.yaml is located)
• --skip-version-check: Skip the check for a new CLI version being available
• --verbose: Enable verbose logging, useful for troubleshooting [env: METAPLAYCLI_VERBOSE]