> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# External databases and private routes

> Declare exact external services, request scoped egress, and connect private-only databases without opening general network access.

<Note>
  **Evolving.** This area is visible in the product, but it is still evolving and should not be treated like a fully mature surface yet.
</Note>

## Goal

Reach a legitimate external database or service through the smallest auditable network grant.

## Prerequisites

* A StackShift hosted project
* The destination hostname and port
* A connected node for private-only routes

## Workflow

<Steps>
  <Step>
    Open the project Security tab and review dependencies detected from configured environment variables.
  </Step>

  <Step>
    Declare any missing destination using only hostname, port, protocol, purpose, and TLS requirements.
  </Step>

  <Step>
    Request an exact destination grant with an expiry.
  </Step>

  <Step>
    For a private-only endpoint, request a connected-node, VPN, or peering route and wait for approval.
  </Step>

  <Step>
    Deploy after the dependency and route state are approved.
  </Step>
</Steps>

## Supported dependency patterns

Exact hostname and port grants support public services such as Neon, Supabase, public AWS RDS, PlanetScale, Upstash, MongoDB Atlas, and equivalent providers. PostgreSQL, MySQL, Redis, MongoDB, SMTP, and generic TCP or TLS endpoints can be declared.

StackShift parses configured connection strings inside the control plane and retains endpoint metadata only. Usernames, passwords, tokens, complete URLs, and raw environment values are not copied into grants, incidents, or network logs.

## Grant rules

* Destination-scoped grants can last up to 90 days.
* Broad public-egress requests require explicit operator approval and expire within seven days.
* Approval is an operator action; declaring a Terraform resource or calling an SDK never self-approves access.
* Expired and revoked grants fail closed.

## Terraform example

```hcl theme={null}
resource "stackshift_workload_external_dependency" "neon" {
  project_id  = stackshift_project.api.id
  environment = "production"
  hostname    = "ep-example.eu-central-1.aws.neon.tech"
  port        = 5432
  protocol    = "tls"
  purpose     = "Primary PostgreSQL database"
  tls_required = true
}

resource "stackshift_workload_egress_grant" "neon" {
  project_id   = stackshift_project.api.id
  dependency_id = stackshift_workload_external_dependency.neon.id
  environment  = "production"
  protocol     = "tls"
  hostname     = stackshift_workload_external_dependency.neon.hostname
  port_start   = 5432
  port_end     = 5432
  purpose      = "Primary PostgreSQL database"
  expires_at   = "2026-11-18T00:00:00Z"
}
```

## Private-only services

A private-only RDS instance or any RFC1918 destination cannot be reached from ordinary hosted egress. The project must target a connected node that already has an approved path through its VPC, VPN, or peering connection.

StackShift validates the route before deployment and reports a waiting-for-network-approval state instead of letting the application fail later with an unexplained connection timeout.

## Expected result

<Check>
  The workload can reach only the approved endpoint and port while credentials remain in the project environment rather than security records.
</Check>

## Common failures

<Warning>
  * A private RDS address has no approved route. Connect a node with the required private network path, VPN, or peering first.
  * The hostname resolves to a private, link-local, metadata, multicast, or otherwise protected address without an approved private route.
  * The grant expired. Request a replacement rather than widening the policy.
  * The provider rotates public addresses. Keep using the approved hostname so StackShift can reconcile its TTL-bound address set.
</Warning>

## Related guides

<CardGroup cols={2}>
  <Card title="Hosted egress and admission" href="/workload-security/hosted-egress-and-admission">
    Understand the image admission receipt and restricted outbound network policy applied to hosted customer workloads.
  </Card>

  <Card title="Private networking and connections" href="/applications/private-networking-and-bindings">
    Connect one service to another so StackShift injects the internal URL as an environment variable — no IPs or hostnames to copy, and private services never touch the public internet.
  </Card>

  <Card title="Provider resources and imports" href="/infrastructure-as-code/resources-and-imports">
    Implementation reference for StackShift provider resources, import IDs, action semantics, and caveats.
  </Card>
</CardGroup>