th database: Managed Database from your terminal

About

A Managed Database lives in your Project’s private network (VPC). Apps in the same Project reach it at its private address; from your computer, turn on the public TLS endpoint and allow your own IP first. With an empty allow list nobody can connect from outside.

Databases are billed by the hour from the Project’s wallet; th database sizes lists the sizes for --size.
th database connect opens the engine’s own client (psql, mysql or mariadb) with the credentials passed in the environment, never on the command line. The client must be installed on your computer.
Backups (manual and automated) are billed by stored GB. Storage only grows; it never shrinks.

More in the help centre: How databases work.

How-to guides

Create a database

Shell

th database engines
th database sizes
th database create app-db --engine postgres --size <size-id> --storage 20GB --backups

Leave out --version for the recommended version. Instead of --size you can give --cpu and --memory.

Connect from your computer

Find your public IP address (for example from your router or a “what is my IP” page).
Turn on the public endpoint for that address only: th database public app-db --enable --allow 203.0.113.7/32.
Run th database connect app-db. psql (or mysql) opens, connected over TLS.

Shell

th database public app-db --enable --allow 203.0.113.7/32
th database connect app-db
th database connect app-db -- -c "select now()"

Arguments after -- go to the client. For your app’s settings, th database credentials app-db prints the user, password and connection URLs.

Home and mobile IP addresses change. If connecting stops working, run th database public again with your new address (--allow replaces the list).

Back up and restore

Shell

th database backups create app-db
th database backups list app-db
th database backups restore app-db <backup-id>
th database backup-policy app-db --enable --hours 24 --window 2 --keep 7

Restoring replaces the database’s data with the backup. Make a fresh backup first if you may need today’s data.

Commands

Command	Description
`th database create`	Creates a Managed Database instance.
`th database list`	Lists the Managed Database instances of the active Project.
`th database describe`	Shows the engine, size, status and addresses of a database.
`th database engines`	Lists the engines and versions a new database can run.
`th database sizes`	Lists the sizes for `--size`.
`th database connect`	Opens the engine's own client (psql, mysql/mariadb, redis-cli/valkey-cli) with the credentials passed through the environment, never the command line.
`th database credentials`	Prints the user, password and connection URLs of a database.
`th database public`	Turns the public TLS endpoint on or off.
`th database resize`	Changes the size of a database.
`th database stop`	Stops a database.
`th database start`	Starts a stopped database.
`th database backups create`	Starts a manual backup.
`th database backups list`	Lists a database's backups, newest first, and its backup policy.
`th database backups restore`	Replaces the database's data with a backup (by ID or name).
`th database backups delete`	Deletes a backup (by ID or name).
`th database backup-policy`	Shows or changes automated backups.
`th database replicas create`	Creates a read replica of database NAME, by default the same size.
`th database replicas list`	Lists the read replicas of a database (or of a replica's primary).
`th database replicas promote`	Stops replication and makes the replica a writable database of its own.
`th database delete`	Deletes a database and its data.

`th database create`

Creates a Managed Database instance.

Syntax

Shell

th database create NAME --engine postgres|mysql|mariadb [--version V] [--region R] [--size ID | --cpu N --memory M] [--storage 10GB] [--disk ssd|hdd] [--public --allow CIDR,...] [--backups --backup-hours N --backup-window H --backup-keep N]

It is billed by the hour from the Project's wallet; see sizes with: th database sizes

Examples

A PostgreSQL database with the recommended version

Shell

th database create app-db --engine postgres

MySQL with a custom size

Shell

th database create shop --engine mysql --cpu 1 --memory 2Gi --storage 20GB --disk ssd

Open to one address, with automated backups

Shell

th database create app-db --engine postgres --public --allow 203.0.113.7/32 --backups

Positional arguments

Name	Description
`NAME`Required	The database name.

Parameters

Name	Type	Default	Description
`--engine`Required	string		Engine: postgres\|mysql\|mariadb (or an engine ID from th database engines)
`--version`	string	`the recommended one`	Engine version
`--size`	string		Size ID from th database sizes
`--cpu`	string		vCPU, e.g. 0.5, 1, 2
`--memory`	string		Memory, e.g. 512Mi, 1Gi, 4Gi
`--storage`	string	`10GB; grows later, never shrinks`	Storage, e.g. 10GB
`--disk`	string		Disk type: ssd or hdd
`--public`	flag		Open a public TLS endpoint (only `--allow` addresses may connect)
`--allow`	list		Addresses allowed on the public endpoint, e.g. 203.0.113.10/32 (repeatable, comma-separated)
`--bandwidth`	number		Public endpoint bandwidth in Mbps (1–1000, default 10)
`--backups`	flag		Turn on automated backups (billed by stored GB)
`--backup-hours`	number		Backup every N hours: 6, 12, 24 (default) or 168
`--backup-window`	number	`2`	Hour backups start, 0–23 Asia/Bangkok
`--backup-keep`	number	`7`	Automated backups kept, 1–90

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th database list`

Lists the Managed Database instances of the active Project.

Syntax

Shell

th database list

Examples

List databases

Shell

th database list

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th database describe`

Shows the engine, size, status and addresses of a database.

Syntax

Shell

th database describe NAME

Examples

Engine, size, status and addresses

Shell

th database describe app-db

Positional arguments

Name	Description
`NAME`Required	The database name.

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th database engines`

Lists the engines and versions a new database can run.

Syntax

Shell

th database engines

Examples

Engines and versions

Shell

th database engines

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th database sizes`

Lists the sizes for --size.

Syntax

Shell

th database sizes

Examples

Sizes for --size

Shell

th database sizes

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th database connect`

Opens the engine's own client (psql, mysql/mariadb, redis-cli/valkey-cli) with the credentials passed through the environment, never the command line.

Syntax

Shell

th database connect NAME [--public | --private] [-- CLIENT-ARGS...]

By default it uses the public TLS endpoint, which must be enabled and allow your address. --private uses the private address, which is reachable only from inside the Project's VPC. Arguments after -- go to the client.

Examples

Open psql or mysql over the public endpoint

Shell

th database connect app-db

From inside the Project’s VPC

Shell

th database connect app-db --private

Pass arguments to the client

Shell

th database connect app-db -- -c "select now()"

Positional arguments

Name	Description
`NAME`Required	The database name.
`CLIENT-ARGS…`Optional	Arguments passed to the client after `--`.

Parameters

Name	Type	Default	Description
`--public`	flag		Use the public TLS endpoint (default)
`--private`	flag		Use the private address (inside the VPC only)

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th database credentials`

Prints the user, password and connection URLs of a database.

Syntax

Shell

th database credentials NAME [--format json]

The password is shown only to members who may operate it.

Examples

User, password and URLs

Shell

th database credentials app-db

As JSON

Shell

th database credentials app-db --format json

Positional arguments

Name	Description
`NAME`Required	The database name.

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th database public`

Turns the public TLS endpoint on or off.

Syntax

Shell

th database public NAME --enable|--disable [--allow CIDR,...] [--bandwidth MBPS]

Only addresses in --allow may connect (an empty list lets nobody in); --allow replaces the list. Without --enable or --disable, only the list or bandwidth changes.

Examples

Open to one address

Shell

th database public app-db --enable --allow 203.0.113.7/32

Replace the allow list

Shell

th database public app-db --allow 203.0.113.0/24,198.51.100.4/32

Close the public endpoint

Shell

th database public app-db --disable

Positional arguments

Name	Description
`NAME`Required	The database name.

Parameters

Name	Type	Description
`--enable`	flag	Turn the public endpoint on
`--disable`	flag	Turn the public endpoint off
`--allow`	list	Allowed addresses, e.g. 203.0.113.10/32 (repeatable, comma-separated; replaces the list)
`--bandwidth`	number	Bandwidth cap in Mbps (1–1000)

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th database resize`

Changes the size of a database.

Syntax

Shell

th database resize NAME [--size ID | --cpu N --memory M] [--storage GB]

A new vCPU or memory restarts it, so connections drop for a moment. Storage only grows.

Examples

Change the size (restarts once)

Shell

th database resize app-db --size <size-id>

Grow storage

Shell

th database resize app-db --storage 50GB

Positional arguments

Name	Description
`NAME`Required	The database name.

Parameters

Name	Type	Description
`--size`	string	Size ID from th database sizes
`--cpu`	string	vCPU, e.g. 0.5, 1, 2
`--memory`	string	Memory, e.g. 512Mi, 1Gi, 4Gi
`--storage`	string	Storage, e.g. 50GB (grow only)

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th database stop`

Stops a database.

Syntax

Shell

th database stop NAME

Its storage is kept (and billed); start it again with th database start.

Examples

Stop it; storage is kept

Shell

th database stop app-db

Positional arguments

Name	Description
`NAME`Required	The database name.

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th database start`

Starts a stopped database.

Syntax

Shell

th database start NAME

Examples

Start it again

Shell

th database start app-db

Positional arguments

Name	Description
`NAME`Required	The database name.

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th database backups create`

Starts a manual backup.

Syntax

Shell

th database backups create NAME

Backups are billed by stored GB.

Examples

Back up now

Shell

th database backups create app-db

Positional arguments

Name	Description
`NAME`Required	The database name.

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th database backups list`

Lists a database's backups, newest first, and its backup policy.

Syntax

Shell

th database backups list NAME

Examples

Backups and the policy

Shell

th database backups list app-db

Positional arguments

Name	Description
`NAME`Required	The database name.

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th database backups restore`

Replaces the database's data with a backup (by ID or name).

Syntax

Shell

th database backups restore NAME BACKUP [--quiet]

--quiet skips the prompt.

Examples

Replace the data with a backup

Shell

th database backups restore app-db <backup-id>

Positional arguments

Name	Description
`NAME`Required	The database name.
`BACKUP`Required	A backup, by ID or name, from `th database backups list`.

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th database backups delete`

Deletes a backup (by ID or name).

Syntax

Shell

th database backups delete NAME BACKUP [--quiet]

--quiet skips the prompt.

Examples

Delete a backup

Shell

th database backups delete app-db <backup-id>

Positional arguments

Name	Description
`NAME`Required	The database name.
`BACKUP`Required	A backup, by ID or name, from `th database backups list`.

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th database backup-policy`

Shows or changes automated backups.

Syntax

Shell

th database backup-policy NAME [--enable|--disable] [--hours N] [--window H] [--keep N]

Without flags it prints the policy. Backups are billed by stored GB.

Examples

Show the policy

Shell

th database backup-policy app-db

Daily at 02:00 Bangkok time, keep 7

Shell

th database backup-policy app-db --enable --hours 24 --window 2 --keep 7

Positional arguments

Name	Description
`NAME`Required	The database name.

Parameters

Name	Type	Description
`--enable`	flag	Turn automated backups on
`--disable`	flag	Turn automated backups off
`--hours`	number	Back up every N hours: 6, 12, 24 or 168
`--window`	number	Hour backups start, 0–23 (Asia/Bangkok)
`--keep`	number	Automated backups kept, 1–90

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th database replicas create`

Creates a read replica of database NAME, by default the same size.

Syntax

Shell

th database replicas create NAME [--size ID | --cpu N --memory M] [--name DISPLAY]

It is billed like a database of its size.

Examples

A read replica of the same size

Shell

th database replicas create app-db

Positional arguments

Name	Description
`NAME`Required	The database name.

Parameters

Name	Type	Default	Description
`--size`	string		Size ID from th database sizes
`--cpu`	string		vCPU, e.g. 0.5, 1, 2
`--memory`	string		Memory, e.g. 512Mi, 1Gi
`--name`	string	`"<primary> · Replica N"`	Display name

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th database replicas list`

Lists the read replicas of a database (or of a replica's primary).

Syntax

Shell

th database replicas list NAME

Examples

List read replicas

Shell

th database replicas list app-db

Positional arguments

Name	Description
`NAME`Required	The database name.

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th database replicas promote`

Stops replication and makes the replica a writable database of its own.

Syntax

Shell

th database replicas promote REPLICA [--quiet]

This cannot be undone. --quiet skips the prompt.

Examples

Make the replica a database of its own

Shell

th database replicas promote <replica>

Positional arguments

Name	Description
`REPLICA`Required	The read replica to promote.

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th database delete`

Deletes a database and its data.

Syntax

Shell

th database delete NAME [--quiet]

--quiet skips the prompt. A database with deletion protection on must have it turned off in the Console first.

Examples

Delete the database and its data

Shell

th database delete app-db

Positional arguments

Name	Description
`NAME`Required	The database name.

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

Help centre: the th command line