External access

External access lets you reach a PostgreSQL database from outside HCode: psql on your laptop, a desktop client, or a service hosted somewhere else. You connect with an access token instead of the database password, and you can revoke a token at any time.

External access is off for every new database, and it isn't available for Redis. Your app on HCode should keep using the internal connection string.

If an app in the same project is given the external address anyway, HCode points it at the internal one when it deploys or restarts the app. The host and port in a connection string become the internal host and 5432, and a separate port setting next to a host setting, such as PGPORT with PGHOST or DB_PORT with DB_HOST, changes to 5432 with it. The password isn't changed, though, so give the app the internal connection string with the database password rather than relying on this. Environment variables lists the settings this applies to.

#Turn it on

1. Go to Databases and find the database's card.
2. In the External access row, click the switch. The row changes from "Internal only" to "Connections allowed from outside".
3. Click Create token.
4. If you like, fill in Label (optional) with something that tells you where the token is used, such as the machine.
5. Under Expires in, choose 1h, 24h, 7d, 30d or Never. The default is 7d.
6. Click Create token.
7. Copy the connection string from the Token created window and store it somewhere safe.

The dashboard shows the token once: "Copy this connection string now. You won't see it again." If you lose it, revoke it and create another.

#Host, port and connection string

The database gets a public host name based on its name, and the port is 15432:

db-<name>.db.hcode.site:15432

The card shows the exact host under External host. The connection string you copy has this shape:

postgresql://u1a2b3c4d:<dbt_token>@db-my-app.db.hcode.site:15432/db_my-app?sslmode=require

The user and database are the same as for the internal connection. The password is the token, which starts with dbt_. The internal database password does not work from outside. The card also shows the string as a template, with <dbt_token> where the password goes, so you can rebuild it for any token you still have.

Connect with psql like this:

psql "postgresql://u1a2b3c4d:[email protected]:15432/db_my-app?sslmode=require"

Turning external access off and on again keeps the same host name, but every token is gone and you need a new one.

#TLS requirements

External connections must use TLS 1.2 or newer, which sslmode=require in the string takes care of. HCode finds your database from the host name your client sends during the TLS handshake, so:

• connect using the host name, not an IP address;
• use a client that sends the host name (SNI) when it starts TLS.

A connection without TLS, or without a host name, is closed before it reaches the database.

#Manage tokens

The card lists active tokens with their label and when they expire, for example "Expires 5d", or "Permanent" for a token that never expires.

• Click Revoke next to a token to stop it working immediately.
• A database can have at most 10 active tokens. Creating an eleventh is refused with "maximum active tokens reached".
• An expired token stops working at its expiry time and drops off the list.

Prefer tokens that expire. The dashboard warns about permanent ones: "Permanent tokens never expire. Consider using a temporary token for better security."

#Turn it off

Click the same switch again. HCode revokes every token for the database at once, and new connections from outside are refused from then on.

Owners, admins and members can turn external access on and off and manage tokens. See Roles and permissions.