Hubfly spaceDocs
Console

Connect a Cell app

An app binding writes a database's connection details into the environment variables of a Cell project, as secret variables. Your app reads them like any other variable, and Hubfly space keeps them up to date when credentials change. Bindings are listed on the instance's Apps page.

What gets written

EngineVariables (default names)Value
PostgreSQLDATABASE_URLpostgresql://user:password@host:port/database?sslmode=require
MySQLDATABASE_URLmysql://user:password@host:port/database?ssl-mode=REQUIRED
SQLite (libSQL)LIBSQL_URL and LIBSQL_AUTH_TOKENlibsql://host and an access token

You can choose another variable name: up to 128 uppercase letters, numbers and underscores, not starting with a number. For libSQL the token variable is named after the URL variable: a trailing _URL becomes _AUTH_TOKEN (LIBSQL_URL → LIBSQL_AUTH_TOKEN), otherwise _AUTH_TOKEN is appended (NOTES_DB → NOTES_DB_AUTH_TOKEN). These are the names @libsql/client, Drizzle and the Connect page snippets expect.

Connect an app

  1. Open the database and go to Apps, then Connect an app. You need Database admin on the database and edit access to the Cell project; the instance must be running.
  2. Choose the Cell project and the variable name. For PostgreSQL and MySQL, choose the database the URL should open and whether the app gets its own user (see below).
  3. Redeploy the app. Apps read their variables at deploy time, so a running app keeps its old environment until its next deploy.

With the CLI, --to takes a Cell project id or name:

bash
hubfly db bind app-db --to web
hubfly db bind app-db --to reports --env REPORTS_DATABASE_URL --database analytics --new-user --access read_only
hubfly db bind list app-db
hubfly db bind remove app-db <bindingId>      # removes the variables it wrote; --keep-variable keeps them

Your app then reads the variable as usual, for example with node-postgres:

TypeScript
import pg from "pg";

const pool = new pg.Pool({
  connectionString: process.env.DATABASE_URL,
  ssl: { rejectUnauthorized: false }, // encrypted; see Connect and verify TLS to also verify the server
});

Bindings use the public endpoint

The URL points at the instance's public hostname and port, so connected apps need public access to stay on, and the IP allowlist applies to them.

Admin user or dedicated user

ChoiceWhat Hubfly space doesKeep in mind
Admin user (default)The URL uses the instance's admin user and password.Rotating the admin password rewrites the variable; the app fails to connect until it is redeployed with the new value.
Dedicated userHubfly space creates a user for this app with read-write or read-only access to the chosen database and puts it in the URL.Not affected by admin password rotations. Disconnecting the app drops this user; objects it owned are reassigned to the admin user.

A read-write user can also run migrations (it may create objects in its database). Use read-only for reporting or analytics apps.

libSQL tokens for apps

Binding a libSQL database creates a full-access access token for the app, listed under Tokens as App: <project>. It does not expire.

libSQL cannot revoke a single token. Revoking any token, or rotating the instance's credentials, replaces the signing key and invalidates every token. Hubfly space then issues a new token to each connected app and rewrites its token variable automatically; redeploy those apps so they use it.

Disconnecting does not invalidate a libSQL token

Removing a libSQL binding removes its variables, but the token the app already has keeps working. To cut the app off, revoke a token afterwards, which invalidates every existing token.

Rotation and removal

  • Admin password rotation rewrites the URL of every binding that uses the admin user. Dedicated users keep their own passwords.
  • Disconnecting removes the variables the binding wrote, unless you keep them (--keep-variable). It needs edit access to the target project.
  • Deleting the instance removes the variables of all its bindings.
  • Variables are only removed while they still point at this database: if you repointed or reused a variable, Hubfly space leaves it alone.
  • After connecting, disconnecting or rotating credentials, redeploy the app so it picks up the change.
Something unclear or out of date? Emailsupport@hubfly.spaceBack to top