Database connections and tunneling

Live. This area is documented as current, user-reliable behavior.

Goal

Connect through the right endpoint and publish native database access for external clients when needed.

Prerequisites

An existing database

Workflow

Read the stable hostname, port, database name, username, and TLS details from the database page.

Choose the private or public network endpoint, then the direct or pooled role and protocol offered for that database.

For external access, choose Direct connection or StackShift tunnel and set a client IP policy.

Wait for the public policy to become active, download the CA, and verify the hostname with a native client.

Smoke-test through the same stable endpoint after restore, promotion, or rollback.

Stable connection details are authoritative

Use only the connection information displayed for the logical database. Do not infer a container name, node IP, physical generation, or hidden candidate address. Import candidates never expose credentials and never inherit public access.

Treat the stable hostname as the application-facing identity.
Use the required TLS mode and CA information shown by the product.
Retrieve credentials on demand and avoid copying them into tickets, logs, or documentation.
Use application bindings where available instead of manually reconstructing connection strings.

Connection pooling

Connection pooling is available where the database and plan support it. When enabled, the database exposes a pooler host/port for application traffic with many short-lived connections. The direct endpoint remains necessary for clients that depend on session-level behavior.

Transaction mode: a connection is assigned for the duration of a transaction. This suits most applications.
Statement mode: the most aggressive mode, assigning per statement — only for workloads that tolerate it.
Migrations, administrative clients, session variables, prepared statements, and similar features may require direct access.

Private and public access

Public access does not replace the private endpoint. Direct uses a public listener on the assigned database node. StackShift tunnel carries native TCP traffic through db-tunnel.stackshift.cloud to the private database endpoint. The client needs no tunnel software and the node needs no public database listener. The edge enforces restricted CIDRs using the original client IP; database TLS passes through to the database. The direct-access firewall correction is implemented but unreleased. Updated node agents carry per-packet database policy approval into the host iptables/ip6tables INPUT chain; they do not open a port range. The existing recovery and watchdog paths restore that handoff. Restricted sources, expired policies, and revoked endpoints remain blocked by the earlier database policy chain. With the matching worker update, direct Open to internet policies must pass a control-plane TCP connection check for every published endpoint before activation is recorded. A timeout reports public_endpoint_unreachable and follows normal retries. This check proves TCP reachability, not client authentication or TLS configuration. Restricted policies retain their allowlist and existing readiness evidence; the worker is not automatically added to permitted sources. Tunnel access keeps its existing edge verification. Tunnel access is available for qualified hosted and customer-added nodes. Supported engines are PostgreSQL, MySQL, MariaDB, Redis, and ClickHouse. Customer-added nodes need a current tunnel-ready agent heartbeat. If a connected node is waiting for the relay update, use Update agent on its Nodes page, wait for a fresh heartbeat, then reopen Credentials. Credentials shows a specific reason when the database or node is still ineligible.

Restricted by IP: supply client CIDRs and an expiry; renew before expiry.
Open to internet: explicitly acknowledge exposure; managed renewal keeps the policy active until revoked.
Transport is fixed for a policy. Revoke it and wait for withdrawal before creating a policy with a different transport.
A tunnel never falls back to direct. Revocation withdraws the public listener and sessions.

Enable a tunnel in the dashboard

Open the database, select Credentials, then the Public tab. The Create database form offers the same network and transport choices.
Choose StackShift tunnel, then Restricted by IP with your client CIDR and expiry, or Open to internet with the required acknowledgement.
Wait for Active. Switch Credentials to Public and select the protocol endpoint. ClickHouse can have separate native and HTTP ports.
Download the CA. Use the displayed hostname, assigned port, connection string, and TLS server name; do not substitute the engine default port.

Public-access API

Use the same suffix for project databases at /api/v1/projects/{projectID}/databases/{databaseID} or standalone databases at /api/v1/databases/{databaseID}. Creation returns a policy before reconciliation finishes. Poll /public-access until active_policy.status is active, then fetch /credentials for the verified public endpoint. Set a unique Idempotency-Key for each create request.

Restricted tunnel access

BASE="https://api.stackshift.cloud/api/v1/databases/{databaseID}"
EXPIRES_AT="$(python3 -c 'from datetime import datetime, timedelta, timezone; print((datetime.now(timezone.utc) + timedelta(days=7)).isoformat().replace("+00:00", "Z"))')"
curl -X POST "$BASE/public-access" \
  -H "Authorization: Bearer $STACKSHIFT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: migration-access-001" \
  --data-binary @- <<EOF
{"transport":"tunnel","access_mode":"restricted","allowed_cidrs":["198.51.100.42/32"],"expires_at":"$EXPIRES_AT"}
EOF
curl -H "Authorization: Bearer $STACKSHIFT_TOKEN" "$BASE/public-access"
curl -H "Authorization: Bearer $STACKSHIFT_TOKEN" "$BASE/credentials"

Open access and revoke

BASE="https://api.stackshift.cloud/api/v1/databases/{databaseID}"
curl -X POST "$BASE/public-access" \
  -H "Authorization: Bearer $STACKSHIFT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: public-access-001" \
  -d '{"transport":"tunnel","access_mode":"anywhere","acknowledge_public_exposure":true}'
curl -X POST -H "Authorization: Bearer $STACKSHIFT_TOKEN" "$BASE/public-access/revoke"

Connect a native client

Use the exact public connection string from Credentials with the downloaded CA and full hostname verification. Native psql, mysql, redis-cli, and ClickHouse clients connect to the assigned edge port like any other TCP database endpoint. The edge does not receive database passwords or terminate database TLS. Keep credentials and CA files out of source control.

PostgreSQL example

# Set PORT, DB_NAME, and DB_USER from the active Public endpoint in Credentials.
# Download its CA as ./database-ca.pem. -W prompts for the password.
psql "host=db-tunnel.stackshift.cloud port=$PORT dbname=$DB_NAME user=$DB_USER sslmode=verify-full sslrootcert=./database-ca.pem" -W

What transfer promotion preserves

Private and public hostname and port.
Database name, username/password identity, and credential fingerprint.
CA and TLS policy.
Allowlist or anywhere public-access mode.
Proxy and firewall policy.

Expected result

A native client connects to the active endpoint with the displayed credentials and verified database TLS.

Common failures

Using a stale copied connection string instead of reopening current database details.
Sending migration or session-dependent traffic through an incompatible pooler mode.
Pointing an application at a physical candidate or node address instead of the stable hostname.
Assuming public access is required when the application can use the private endpoint.

Create a database

Create a hosted or connected-node database with private, direct public, or StackShift tunnel access.

Import and export a database

Move complete PostgreSQL or MySQL databases as portable SQL with resumable uploads, private candidates, structural validation, explicit promotion, and 24-hour rollback.

Back up and restore a database

Use durable recovery storage correctly and understand why backups are independent from portable SQL transfers.

Database troubleshooting

Diagnose provisioning, tunnel access, deletion, backup, transfer, and recovery failures.

​Goal

​Prerequisites

​Workflow

​Stable connection details are authoritative

​Connection pooling

​Private and public access

​Enable a tunnel in the dashboard

​Public-access API

​Connect a native client

​What transfer promotion preserves

​Expected result

​Common failures

​Related guides

Create a database

Import and export a database

Back up and restore a database

Database troubleshooting

Goal

Prerequisites

Workflow

Stable connection details are authoritative

Connection pooling

Private and public access

Enable a tunnel in the dashboard

Public-access API

Connect a native client

What transfer promotion preserves

Expected result

Common failures

Related guides