Connecting an application to a database sounds like one configuration change:

DATABASE_URL=postgresql://user:password@host:5432/app 

In practice, I kept repeating a longer sequence:

  1. create the database;
  2. find its host and port;
  3. copy the username and password;
  4. build the connection URL without breaking its escaping;
  5. paste it into the application's environment;
  6. make sure both containers share a network;
  7. restart or redeploy the application;
  8. remember where that credential was copied when it needs to change.

The connection string was only the visible part. The real relationship contained both configuration and network access.

This is the problem behind database links in Nitrobase.

Nitrobase has only recently launched and is still in Beta. This feature does not try to become a database proxy or a service mesh. Its purpose is smaller: connect an application and a database on the same VPS through an isolated Docker network, then give the application the correct connection values without requiring manual copy-and-paste.

A URL alone does not create connectivity

Suppose I add this environment variable to an application:

DATABASE_URL=postgresql://app:secret@database:5432/app 

That value is useful only if database resolves to the correct container and the application can reach it.

Application configuration ✅ has DATABASE_URL Docker networking ❓ can “database” be resolved? Database permissions ❓ can this login access “app”? Runtime state ❓ has the application been restarted? 

The opposite is also possible: two containers share a network, but the application has no credential with which to authenticate.

network without credentials = reachable but unusable credentials without a network = configured but unreachable network + credentials = an actual connection 

Nitrobase treats the link as the combination of those pieces.

What happens when I link a database?

A database link connects one managed database to one application on the same server.

The workflow looks like this:

Choose database + application │ ▼ Create a private per-link Docker network │ ┌──────┴──────┐ ▼ ▼ attach database attach app services │ │ └──────┬──────┘ ▼ Generate DATABASE_URL and selected env values │ ▼ Redeploy the app so it receives them 

The application receives a full connection URL using an internal container address. Optionally, Nitrobase can also provide the individual parts:

DATABASE_URL=postgresql://app:secret@database-container:5432/app DATABASE_HOST=database-container DATABASE_PORT=5432 DATABASE_USER=app DATABASE_PASSWORD=secret DATABASE_NAME=app 

The exact variable names depend on the database engine and can be changed during linking to match what the application expects.

One relationship, one private network

I did not want every application on a VPS to join one large shared database network.

Instead, each link receives its own internal Docker network:

 VPS ┌──────────────────────────────────────────┐ │ │ │ app-a ───── private link A ─────┐ │ │ ▼ │ │ PostgreSQL │ │ ▲ │ │ app-b ───── private link B ─────┘ │ │ │ │ app-c ✕ no link, no database network │ │ │ └──────────────────────────────────────────┘ 

app-a and app-b can reach the database because each has an explicit link. app-c does not receive access merely because it happens to run on the same VPS.

The networks are created as internal networks. The database remains unavailable from outside the host unless its port is separately published.

Connection path Available by default?
Linked application → database Yes
Unlinked application → database No
Internet → database port No
SSH tunnel → loopback-published port Only when configured
External network → published port Only when explicitly enabled

This keeps “the database exists on this server” separate from “the database should accept connections from the network.”

Why the network does not use a friendly shared service name

Docker Compose normally makes service names available through DNS on a Compose network. That is convenient inside one application:

services: api: environment: DATABASE_HOST: db db: image: postgres 

It becomes risky on a network shared by unrelated Compose projects.

Imagine two applications, both with a service named db. If those services join the same shared network under that alias, the name may no longer identify the intended database reliably.

app-one/db ──┐ ├── shared alias “db” ──► ambiguous app-two/db ──┘ 

Nitrobase avoids declaring the link network directly in either Compose file. After deployment, it attaches containers by their unique container names. The generated connection URL uses the database container's unique name rather than a generic service alias.

db ❌ potentially ambiguous database-a1b2c3d4-db ✅ identifies one container 

It is a small implementation detail, but it prevents one application's ordinary service name from colliding with another application's database path.

A link should not require the database superuser

The fastest way to connect an application is to reuse the database's main login. It is also usually more access than the application needs.

Nitrobase can link with either:

  • the database's main credential; or
  • another login created for a specific application and database.
Main database login ├── administrative access ├── maintenance operations └── broad permissions Application login ├── one application ├── one database └── only the permissions it needs 

The second model reduces the impact of an application credential being exposed. It also makes ownership clearer: when the application is retired, its database login can be removed without rotating the credential used by every other service.

Nitrobase does not infer the ideal permission model for arbitrary software. The database user and grants still need to match the application. The link simply makes it practical to use a dedicated credential rather than encouraging reuse through copy-and-paste convenience.

Why I prefer injecting the URL over displaying it repeatedly

Every time a connection string is copied, it gains another place where it can remain:

database page ↓ copy clipboard history ↓ paste local notes ↓ paste .env file ↓ maybe commit repository history 

Nitrobase stores database passwords and link credentials encrypted. When an application is rendered for deployment, the link produces the environment values that application needs.

The goal is not to claim the secret never reaches the application—it must, or authentication cannot work. The goal is to reduce unnecessary handling and avoid turning the connection URL into a value that people repeatedly move through browsers, chat, notes, and repositories.

Linking and redeploying are separate decisions

Creating a link changes the desired relationship, but a running container does not gain new environment variables dynamically.

The application needs to be recreated with the new environment:

Create link │ ├── network can be prepared └── env is part of next application render │ ▼ redeploy │ ▼ application starts with DATABASE_URL 

The link dialog can redeploy the application immediately. It can also save the relationship without redeploying, which is useful when several configuration changes should be applied together.

This distinction avoids pretending that updating configuration in a control panel magically changes the environment of an already-running process.

Why links currently require the same server

A Docker network exists on one Docker host. It cannot privately attach a container running on another VPS.

VPS A: application ──────╳────── database : VPS B no shared local Docker network 

Nitrobase therefore links only applications and databases on the same managed server.

For applications on another server, the choices are different:

  1. move the application or database so they share a host;
  2. publish the database port and protect it with a firewall or private network;
  3. use an external tunnel or VPN designed for cross-server connectivity.

I prefer an explicit limitation here. Calling a public database address a “private link” would hide a meaningful change in the security boundary.

What happens when the database moves?

A hard-coded connection URL combines identity and location:

protocol + username + password + hostname + port + database 

If the database is restored as a new application or moved to another server, some of those parts may change.

The link is useful because Nitrobase knows which application and database the relationship belongs to. When the application is rendered, the connection values are derived from the current internal endpoint and stored login rather than from a string somebody copied months ago.

This does not eliminate every migration step—cross-server networking still needs an explicit design—but it gives the platform a structured relationship to update instead of an opaque value hidden in an .env file.

My checklist before connecting an application

  • [ ] Are the application and database on the same VPS?
  • [ ] Does the application expect a full URL or separate connection fields?
  • [ ] Is the chosen environment variable name correct?
  • [ ] Can I use a dedicated database login instead of the main account?
  • [ ] Does that login have only the permissions the application needs?
  • [ ] Is the database port still private unless external access is required?
  • [ ] Will the application be redeployed now or during a maintenance window?
  • [ ] Does the application health check prove the database connection works?

The last item matters. A successful container start does not prove that migrations completed or that the application can query its database.

The problem this feature is trying to solve

Copying a connection string is easy. Maintaining the relationship it represents is harder.

A useful database link needs to answer:

  • Which application is allowed to reach this database?
  • Through which network path?
  • Which login does it use?
  • Which environment variables should it receive?
  • When does the running container pick up those values?
  • What must change if either side moves?

Nitrobase tries to make those answers part of one managed relationship instead of spreading them across Docker networks, password managers, .env files, and deployment notes.

It is still a Beta feature and needs testing with more frameworks, database clients, and unusual connection formats. But the principle is simple:

Connecting an application to a database should establish both the route and the credential—not leave half of the relationship in someone's clipboard.

Nitrobase source code: https://github.com/AydenGroup/nitrobase