Connections

A connection is a service depending on a database, made as one thing: web → database. Instead of adding a reference variable for each value the database exposes, you connect the service to the database and Kuppit injects every variable the database exposes, under the names the database uses. The connection then owns those variables. Renaming one, pointing the connection at a different database, or removing it are done on the connection, and the variables follow.

A connection is made on the project's Overview, between a service and a database in the same environment. Right-click the service, or open the ellipsis on its card or its panel, choose Connect to…, then the database. A database the service is already connected to is not offered again. The connection appears as a line between the two; select the line to see what it injects, and to change it.

Changing a connection

Select the connection's line on the Overview. Its panel lists every variable it injects and offers three changes:

• Rename an injected variable with the pencil beside it. The new name must be free on the service.
• Change target to another database beside the service — a database this environment shares from another appears here too, named for where it comes from. Every injected variable moves at once. The new target must expose everything the connection injects.
• Disconnect removes the connection and every variable it injected.

Changing the target and disconnecting ask first, and say what changes; a rename applies at once. None of them touches the running deployment; see when a change takes effect.

What a connection injects

A connection injects the variables its target exposes. For PostgreSQL that is:

Each is injected as a reference: the service stores the pointer, and the value is composed when a deployment is prepared, from the database as it is then. Secrecy follows the variable being referenced. PGPASSWORD and DATABASE_URL are secrets whatever the service calls them.

Every variable is injected under its own name, unless that name is already taken on the service (below). To give one another name afterwards, rename it on the connection: a service that reads DB_URL can receive DATABASE_URL as DB_URL.

A name the service already uses is never taken over. If the service already has a variable called PGHOST, whether a literal or a reference you wrote, the connection is not made under that name: the panel lists every variable the connection would inject, points out the names the service already uses, and asks what to call each. Give those other names, or rename the existing variable first.

On the Variables tab

The variables a connection injects appear on the service's Variables tab like any other reference, marked Connection, with a line saying which connection manages them. They cannot be edited or deleted there; they are changed on the connection, as above.

A reference you wrote by hand to the same database is not part of the connection. It stays where it is when the connection changes or is removed, and it is still edited on the Variables tab.

When a change takes effect

A connection changes the service's variables, and a variable change never touches the running deployment. The service shows Runtime configuration has changed; choose Redeploy now, or wait for the next push. See when a change takes effect.

Deleting either end

Deleting the database removes the connection and every variable it injected, exactly as it removes references written by hand. Kuppit names each connected service before you confirm. Deleting the service takes its connections with it and leaves the database untouched.

In a new environment

When a named environment is created from another, a connection comes across as a connection, against whatever the new environment provides for the database: the new copy, the clone, or the shared instance. A connection to a component the new environment leaves out is dropped, with the variables it would have injected.

Where a connection can point

A connection targets a resource in the same environment as the service, like any reference. To depend on another environment's database, share it into this environment first; a connection to the shared database is then a connection like any other.