Hubfly spaceDocs
Console

hubfly db

hubfly db creates and operates Managed Databases: PostgreSQL, MySQL and SQLite (libSQL) that Hubfly space runs for you. It covers the whole lifecycle, from quoting a price to running SQL, binding a database to an app, exporting data and changing configuration. hubfly database and hubfly databases are aliases.

Basics

  • <db> is a database instance id or name. When two managed projects use the same name, add --project <id|name>.
  • Hubfly space chooses where managed databases run, so there is no --region flag.
  • Sizes are nano, small, medium, large and xlarge, or a custom --cpu and --memory; hubfly db engines lists them with prices.
  • Commands that print data accept --json. Passwords and tokens are printed only with --reveal, or once when they are created.
  • Run hubfly db help for the full usage text.

terminal

$ hubfly db engines
$ hubfly db create app-db --engine postgresql --size nano --project new
$ hubfly db connect app-db
$ hubfly db bind app-db --to web

Create And Inspect

usage
hubfly db list [--project <id|name>] [--json]
hubfly db engines [--json]
hubfly db info <db> [--json]
hubfly db create [<name>] [--engine postgresql|mysql|libsql] [--version <v>]
                 [--size <preset>|--cpu <n> --memory <mib>] [--storage <gib>]
                 [--project <id|name|new>] [--project-name <name>]
                 [--database <name>]
                 [--private] [--allow <cidr>]... [--allow-my-ip]
                 [--yes] [--no-wait] [--timeout <duration>] [--json]
CommandWhat it does
db listDatabases in your managed projects: name, engine and version, status (including a running operation), size, monthly price, project and id.
db enginesWhether new databases are being accepted, the engines and versions (default, LTS), size presets with monthly prices, the storage range and your instance limit.
db infoEngine and version (and whether an update is available), status, size, storage, price, host and port, default database, admin user, TLS, public access and allowlist, deletion protection and any pending restart. With --json it returns instance and connection.
db createChecks your input against the catalog, quotes the monthly price, asks you to confirm, creates the database and waits until it is ready. It prints the host, port, database and user, never the password.
Create flagMeaning
--enginepostgresql, mysql or libsql. In a terminal you are asked; otherwise the default is postgresql.
--versionEngine version such as 17 or 9.7. Defaults to the engine's default version.
--sizeA size preset. Defaults to the smallest preset with enough memory for the engine (MySQL needs 1 GiB).
--cpu, --memoryA custom size instead of a preset: 0.25–8 vCPU in 0.25 steps, memory in MiB in 256 MiB steps.
--storageStorage in GiB, 1–500. Defaults to 10. It can grow later but never shrink.
--projectThe managed project to create it in, or new for a new managed project. In a terminal you can pick one.
--project-nameName of the new project with --project new. Defaults to the database name.
--databaseDefault database name (PostgreSQL and MySQL), initially app. The admin user is always admin.
--privateCreate without a public endpoint. See public access.
--allow, --allow-my-ipIP allowlist entries; repeat --allow for several. --allow-my-ip adds the address you are connecting from.
--yesAccept the quoted price without a prompt. Required when no terminal is attached.
--no-wait, --timeoutReturn as soon as the create request is accepted, or limit how long to wait (for example 20m).

terminal

# Quote, confirm and wait
$ hubfly db create app-db --engine postgresql --size small --storage 20 --project new
# MySQL 9.7 with a custom size, restricted to one office network, from a script
$ hubfly db create orders --engine mysql --version 9.7 --cpu 1 --memory 2048 --allow 203.0.113.0/24 --project shop --yes
# SQLite over HTTPS
$ hubfly db create notes --engine libsql --project shop --yes

Lifecycle And Settings

usage
hubfly db delete <db> [--yes] [--wait]
hubfly db start|stop|restart <db> [--no-wait] [--json]
hubfly db resize <db> [--size <preset>|--cpu <n> --memory <mib>] [--storage <gib>] [--restart] [--yes] [--no-wait] [--json]
hubfly db upgrade <db> [--yes] [--no-wait]
hubfly db rename <db> <new-name>
hubfly db protect <db> on|off
CommandWhat it does
db deleteDeletes the database immediately and permanently after you type its name (or pass --yes). Deletion protection must be off. --wait follows the deletion until it finishes. Exports already taken stay downloadable until they expire.
db start, stop, restartWaits for the operation unless --no-wait. Stopping disconnects every client; a stopped database pays for storage only.
db resizeQuotes the old and new monthly price and asks you to confirm. The database must be running. Storage can only grow. Adding CPU or memory applies without a restart; reducing memory stops and starts the database. When the new size changes engine settings that need a restart, --restart restarts as part of the resize; otherwise the database shows a pending restart.
db upgradeApplies an available update for the engine's version line, after you confirm. The database restarts during the update. db info shows whether one is available.
db renameChanges the display name. The hostname and connection strings stay the same.
db protectTurns deletion protection on or off.

terminal

$ hubfly db resize app-db --size medium --restart
$ hubfly db resize app-db --storage 50 --yes
$ hubfly db protect app-db on
$ hubfly db stop app-db

Connect

usage
hubfly db url <db> [--database <name>] [--reveal] [--json]
hubfly db env <db> [--database <name>] [--reveal] [--format dotenv|json]
hubfly db credentials <db> [--reveal] [--json]
hubfly db credentials rotate <db> [--yes] [--json]
hubfly db connect <db> [--database <name>] [-- <client args>...]
hubfly db shell <db>
hubfly db cert <db> [--output <file>]
CommandWhat it does
db urlPrints the connection URL in the same format app bindings use, including the TLS parameter. The password is masked unless you pass --reveal, which is recorded in the activity log. For libSQL it prints the libsql:// URL; create a token with db tokens create.
db envPrints DATABASE_URL=…, or the libSQL URL variable, ready for a .env file or as JSON.
db credentialsShows the admin user and a masked password; --reveal shows the password.
db credentials rotateReplaces the admin password and prints the new one once. App bindings that use the admin user get the new URL (redeploy those apps); update any other client yourself. On libSQL it replaces the token signing key instead, which invalidates every token; connected apps receive new tokens.
db connectStarts psql or mysql on your machine with TLS required. It first checks that your IP may connect and tells you the fix if not (hubfly db network allow <db> --my-ip). The password goes through the environment or a temporary file, never the command line. Arguments after -- are passed to the client. libSQL is HTTPS only: use db query or a libSQL client.
db shellOpens a SQL shell that runs on Hubfly space through the same terminal connection as hubfly ssh, so nothing needs to be installed: psql signed in as the admin role, or the mysql client, which asks for the admin password. PostgreSQL and MySQL; the database must be running.
db certWrites the instance's CA certificate (PEM) to standard output or --output, for clients that verify the server (sslmode=verify-full).

terminal

$ hubfly db url app-db --reveal
$ hubfly db env app-db --reveal >> .env
$ hubfly db connect app-db -- -c 'select version()'
$ hubfly db cert app-db --output app-db-ca.pem

Run SQL

usage
hubfly db query <db> [<sql>|--file <path|->] [--database <name>] [--write] [--max-rows <n>]
                [--timeout <duration>] [--format table|json|csv]

db query runs SQL through Hubfly space, like the Dashboard's SQL editor, so it works without a local client or an allowlist entry. SQL comes from the argument, from --file (- for standard input) or from piped input. Queries are read-only unless you pass --write. Results print as a table, or with --format json or csv (CSV takes the first result set). The command exits with a non-zero status when a statement fails.

terminal

$ hubfly db query app-db 'select count(*) from users'
$ hubfly db query app-db --file migrations/0004_add_index.sql --write
$ hubfly db query app-db 'select * from orders' --max-rows 1000 --format csv > orders.csv

Databases, Users, Tokens, Extensions

usage
hubfly db databases [list] <db> [--json]
hubfly db databases create <db> <name> [--owner <user>] [--json]
hubfly db databases delete <db> <name> [--force] [--yes]
hubfly db users [list] <db> [--json]
hubfly db users create <db> <name> [--preset read_only|read_write|admin] [--databases <a,b>|--all-databases] [--json]
hubfly db users update <db> <name> [--preset <preset>] [--databases <a,b>|--all-databases] [--json]
hubfly db users delete <db> <name> [--reassign-to <user>] [--yes]
hubfly db users rotate <db> <name> [--yes] [--json]
hubfly db tokens [list] <db> [--json]                                  (SQLite/libSQL)
hubfly db tokens create <db> <name> [--access read_only|full_access] [--expires <days>] [--json]
hubfly db tokens revoke <db> <tokenId> [--yes]
hubfly db extensions [list] <db> [--database <name>] [--json]          (PostgreSQL)
hubfly db extensions install <db> <name> [--database <name>]
hubfly db extensions remove <db> <name> [--database <name>] [--cascade] [--yes]
CommandWhat it does
db databasesPostgreSQL and MySQL. create adds a database (optionally owned by --owner). delete asks you to type the database name; it fails while sessions use the database unless --force, which ends those sessions first.
db usersPostgreSQL and MySQL. Presets: read_only, read_write (can also run migrations) and admin (never a superuser), for --databases a,b or --all-databases. create and rotate print the password once. delete can hand the user's objects to another user with --reassign-to. The admin user created with the instance cannot be deleted.
db tokensSQLite (libSQL). create prints a token once, with read_only or full_access and an optional expiry in days. revoke replaces the signing key, which invalidates every token; connected apps get new tokens automatically.
db extensionsPostgreSQL. Lists available and installed extensions per database, installs one from Hubfly space's allowlist, or removes one (--cascade also drops objects that depend on it).

terminal

$ hubfly db databases create app-db analytics
$ hubfly db users create app-db reporting --preset read_only --databases analytics
$ hubfly db extensions install app-db vector
$ hubfly db tokens create notes ci-reader --access read_only --expires 30

Export And Import

usage
hubfly db export <db> [--database <name>] [--format native|sql] [--output <file>] [--no-wait]
hubfly db exports [list] <db> [--json]
hubfly db exports download <db> <exportId> [--output <file>]
hubfly db import <db> <file> [--database <name>] [--format native|sql] [--yes] [--no-wait]
  • db export starts an export, waits for it and downloads the file. With --no-wait it prints the export id; download it later with db exports download. Exports stay downloadable for 7 days.
  • Formats: PostgreSQL native (a pg_dump custom-format archive) or sql (plain SQL); MySQL and libSQL sql, gzip-compressed.
  • db import uploads a file and restores it into a database after you confirm, because it writes into that database. Files are limited to 5 GB.

terminal

$ hubfly db export app-db --format native --output app-db.dump
$ hubfly db exports app-db
$ hubfly db import staging-db app-db.dump --format native

Read SQL, explorer and exports for how imports behave per engine.

Network And Apps

usage
hubfly db network <db> [--json]
hubfly db network public <db> on|off [--yes]
hubfly db network allow <db> (<cidr>|--my-ip) [--label <text>]
hubfly db network remove <db> <cidr>
hubfly db bind <db> --to <project> [--env <NAME>] [--database <name>] [--new-user [--access read_only|read_write]] [--json]
hubfly db bind list <db> [--json]
hubfly db bind remove <db> <bindingId> [--keep-variable] [--yes]
CommandWhat it does
db networkShows the endpoint, public access and the allowlist with labels.
db network publicTurns public access on or off. Turning it off asks for confirmation: clients outside Hubfly space and apps that use the public host lose access.
db network allow, removeAdds or removes an allowlist entry (up to 64). A bare IP becomes a /32 or /128 range; --my-ip uses the address you connect from.
db bindWrites DATABASE_URL (or --env NAME), or LIBSQL_URL and LIBSQL_AUTH_TOKEN for libSQL, into a Cell project. --new-user creates a dedicated user with read_write or read_only access instead of using the admin user. The app picks the values up on its next deploy.
db bind list, removeLists bindings, or removes one together with the variables it wrote (--keep-variable keeps them).

terminal

$ hubfly db network allow app-db --my-ip --label laptop
$ hubfly db bind app-db --to web
$ hubfly db bind app-db --to reports --env REPORTS_DATABASE_URL --new-user --access read_only

Operate

usage
hubfly db logs <db> [--tail <bytes>] [--follow]
hubfly db metrics <db> [--window <duration>] [--json]
hubfly db operations <db> [--limit <n>] [--json]
hubfly db sessions [list] <db> [--json]
hubfly db sessions cancel|terminate <db> <sessionId> [--yes]
hubfly db insights <db> [--order-by total_time|mean_time|calls] [--limit <n>] [--json]
hubfly db insights reset <db> [--yes]
hubfly db config <db> [--all] [--json]
hubfly db config set <db> <key>=<value>... [--restart now|later] [--note <text>] [--yes]
hubfly db config history <db> [--limit <n>] [--json]
hubfly db config revert <db> <revisionId> [--restart now|later] [--yes]
CommandWhat it does
db logsRecent server logs, with passwords and tokens scrubbed. --follow keeps printing new lines until you press Ctrl-C.
db metricsCPU, memory, storage and network figures, plus database statistics, over a window such as 1h.
db operationsRecent operations (create, resize, restart, export…) with status, current step and error.
db sessionsPostgreSQL and MySQL sessions: user, database, client address (marked when it arrived through Hubfly space's proxy), state, duration and query. cancel stops the running query; terminate closes the session.
db insightsPostgreSQL and MySQL query statistics, ordered by total time, mean time or calls. insights reset clears them.
db configPostgreSQL and MySQL. config set validates the change, shows what changes and what needs a restart, then applies it after you confirm. Settings that need a restart wait for the next restart unless you pass --restart now. history lists applied revisions and revert returns to one.

terminal

$ hubfly db logs app-db --follow
$ hubfly db insights app-db --order-by mean_time --limit 10
$ hubfly db config set app-db work_mem=16MB --note 'faster sorts'
$ hubfly db config history app-db

Scripting And Secrets

  • JSON output. With --json, standard output carries only JSON; prompts and progress go to standard error.
  • Confirmations. Creating, resizing, deleting and other destructive commands ask first. Without a terminal they stop with confirmation required; re-run with --yes instead of guessing; pass --yes once you have reviewed the change.
  • Secrets. Passwords appear only with --reveal (an audited reveal) or once when they are created or rotated; tokens appear only when created. --debug never prints them.
  • Waiting. Long operations show progress and wait; --no-wait returns as soon as Hubfly space has accepted the request. Follow it later with hubfly db operations.
  • Exit codes. Non-zero on failure, with distinct codes for usage errors, authentication, conflicts and timeouts. See exit codes.

Use it in CI

Set HUBFLY_TOKEN, pass --yes to accept quotes and confirmations you have reviewed, and read results with --json. For example, hubfly db query app-db --file schema-check.sql --format json fails the job when a statement fails.
Something unclear or out of date? Emailsupport@hubfly.spaceBack to top