Skip to content
flui.cloud

Reach the platform's own database

The other pages in this section are about your own applications, data and clusters. This one is about the database underneath them, the one Flui itself writes to.

If you run an installation, sooner or later you will need to look in there: a row is wrong, a migration only half applied, or a login behaves in a way no log explains. Without a supported route, you would have to reach the machine yourself and guess which server, database and role to use. Flui gives you a route, and keeps it narrow.

The two names

flui db tunnel normally takes an application. Two names are checked before any application is looked up, and they reach the platform instead:

  • platform-postgres: Flui’s own database. Every user, every API key, every encrypted provider token and every application row on this installation is stored in it.
  • identity-provider: the identity provider’s own database, on the same server. Opening it opens every session and credential on the installation.

There are no others. Both hold the product itself, so the rules below are stricter than anywhere else in these docs.

Why the web console cannot open them

The dashboard has a console for the databases you run. It does not open these two, and no setting changes that.

The refusal is written in one place, with the reason for each name next to it. It does not depend on anything that could go missing, such as a label, an engine declaration or recorded history. Removing a name from that list means deleting a line and the sentence that explains it, and nothing added elsewhere can do it by accident.

The tunnel is a separate route: the CLI, on your own machine, with a native client you bring yourself.

Who may use it

You need authority over the whole installation, at the top scope. A grant on one cluster, or a grant that matches a set of applications, is not enough. Those grants cover what sits inside their scope, and the platform’s database sits underneath every scope.

Three things are checked, in this order:

  1. The right to reach data at all. Every role has it except Platform operator. Without it the call is refused, and the refusal names what is missing.
  2. The credential you use, before anything is loaded. A scoped API key is held to its own scopes even when the person holding it administers the installation. That refusal names the permission the call needs.
  3. Your authority, at the top scope.

If you pass the first two checks but not the third, you get the same answer as for any application that is not yours: there is nothing here. The answer does not say forbidden and does not repeat what you asked for, so probing this route tells you nothing new.

No password crosses the API

When you ask Flui where its database is, the API returns only coordinates: the cluster, database, role and port.

The password is never part of the answer. Your CLI reads it from the cluster afterwards, using the access your profile already has. The secret that opens the product never travels through the product’s own HTTP API, and Flui never opens a connection or runs a statement on your behalf.

For identity-provider, the role you get can read and repair the identity tables. It is not the role that owns them, and it cannot create new ones.

Opening one

Terminal window
flui db tunnel platform-postgres
Terminal window
flui db tunnel identity-provider

You do not name a cluster. Both databases run only on the control cluster, and Flui finds it for you.

The command stays in the foreground. It prints the local host and port, the database, the role, the password, a connection string, and a client command you can paste into another terminal. Press CTRL-C to close it. If the connection drops, it reconnects unless you pass --no-retry.

The local port is 55432 unless you pass --local-port, and it listens on your own machine only. Nothing is exposed to the internet.

Both names use the same local port. To open both at once, give the second one a different --local-port.

The password is printed in your terminal in the clear, because you need it to connect a client, so it stays in your scrollback. Treat that window as you would the credential itself.

Why there is no short alias

A short alias like postgres would read better than platform-postgres, but there is no such alias.

A tenant can legitimately name their own application postgres, and that name resolves to their database. If postgres became an alias for the platform’s database, every existing command using it would silently open a different database, with no error.

So nothing else answers to the reserved names, in any capitalisation.

An unknown name reads as an absence

If you ask for a reserved name that does not exist, you are told there is nothing there, in the same words used for an application that is not yours.

This stops anyone from finding the two names by guessing. Someone who has got this far without knowing them does not learn them here.

Every attempt is recorded

This route should be used rarely, so each use has to be visible afterwards.

The installation records every attempt on the server: who asked, which name they asked for, whether they were allowed through, and, if not, which check stopped them. Refusals are recorded as fully as successful attempts, including requests for a name that means nothing.

The CLI is the only surface

There is no dashboard page for this, and no agent tool. Nothing in the agent’s tools reaches it, so an agent working through its tools cannot ask for it.

That does not make the route unreachable outside the CLI. The route exists behind the API, and someone with authority over the whole installation, using a credential that can change applications, could call it directly. Only the tool is missing. What keeps a narrower key out is the scope check described above.

A SQL prompt on this database is a SQL prompt on the product, so it is meant to be opened from a terminal by a person who holds the installation, not with a click or through something acting for them.

flui db credentials does not answer these names. flui db tunnel is the only command that does. The developer tool flui dev tunnel also forwards the platform’s Postgres to your machine, but it uses your own SSH access to the cluster and skips these checks.

Where this goes next