> ## 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.
# Application and PostgreSQL with an external agent
> Follow governed resource creation, private database binding and evidence-based deployment verification.
**Live.** This area is documented as current, user-reliable behavior.
## Goal
Prepare one Git-based web service and managed PostgreSQL through typed operations, then verify an actual application database write and read.
## Prerequisites
* A connection explicitly authorized for the required actions on the deployed backend.
* A GitHub repository and branch for a web service that can write and read a test record in PostgreSQL.
* Authorized hosting placement and an active PostgreSQL size returned by capabilities. Normal infrastructure quotas and billing apply.
## Workflow
Discover connection identity, resources and capabilities. Gather repository, branch, service settings and the available PostgreSQL size before proposing work.
Review the affected resources and infrastructure estimate. If the estimate is unavailable, keep that limitation explicit rather than inventing a price.
Propose application.create with hosted deployment mode and a retained idempotency key. Obtain independent owner approval or an applicable recorded standing-policy decision.
Retain the resulting Application identity. Propose service.create and database.create with their own stable keys, then inspect their canonical operation results.
Attach the authorized database to the Application where needed, then create the private runtime binding for the web service.
Wait for the database private endpoint and configuration to be ready. Propose release.create for the explicit service IDs and follow its actual controller operations.
Once the exact deployment is healthy, exercise an application endpoint that writes a unique test record and reads the same value back. Report the resource and release links with this evidence.
## Typed objective checks (next release)
Objective and schedule creation accept criteria instead of success\_criteria. Send one list, with 1–20 entries. Each entry has description and kind. Checks apply to each selected target and retain the controller-bound plan, source/configuration revision and two-minute evidence lifetime. Each new criterion also records its server-selected verifier and evidence\_ttl\_seconds (120). Stored evidence records the actual verifier and a fingerprint of the full criterion contract; changing the check parameters invalidates previous evidence. Existing stored histories remain readable. Scheduled HTTP stability requires fresh, distinct observations; rereading one cached result cannot advance the window.
application\_smoke\_test requires smoke.script\_path (a relative .sh file included in the deployed image) and smoke.timeout\_seconds (1–120). Select a project or explicit Application service IDs. The project.smoke\_test.run action requires the inspected deployment\_id and image\_digest, the same script and timeout, and normal independent approval or an applicable standing policy. The script receives STACKSHIFT\_SMOKE\_BASE\_URL and the retained STACKSHIFT\_SMOKE\_ID; it must write/read its own unique test record, assert the result, clean up its test data and exit nonzero on failure. It runs with runtime credentials and may cause external effects. No automatic retry follows an unknown execution outcome. A passed script has two-minute evidence tied to the original observation and active image; changing the deployment requires a new test. Raw stdout/stderr are not returned as objective evidence. service\_connectivity checks supported private consumer bindings, including PostgreSQL SELECT 1. Node.js uses its native HTTP client or pg driver; other runtimes use curl for HTTP and psql for PostgreSQL. Node.js can fall back to those clients when its driver is unavailable. Images must include the selected client; missing clients return unavailable. PostgreSQL requires a trusted sslrootcert and verified TLS. These probes run inside the consuming workload, and do not return credentials or response bodies as evidence. A connection check alone does not prove application persistence. http\_response requires http.path and http.status\_code, with optional body\_equals and max\_duration\_ms. The description is a label; the typed fields define the check.
controller\_health checks the owning runtime controller. HTTP checks use GET on the canonical public HTTPS deployment, forbid redirects and arbitrary hosts, and accept a path without query or fragment. The exact expected status must be 200–299; the optional exact response body is limited to 64 KiB. max\_duration\_ms is a per-request bound from 1 to 8000, including response-body reading, not a percentile or sustained latency claim.
Unknown free-text criteria are rejected instead of being inferred as health or connectivity. Canonical built-in engineering and product-operation criteria remain supported through success\_criteria. A healthy response with the wrong status, body or duration cannot satisfy a typed HTTP check. Use application\_smoke\_test for repository-defined application write/read assertions; HTTP probes alone do not write records or certify persistence.
```json theme={null}
{
"criteria": [
{
"description": "Health endpoint returns the expected version promptly",
"kind": "http_response",
"http": {
"path": "/health",
"status_code": 200,
"body_equals": "ready",
"max_duration_ms": 1000
}
}
]
}
```
## Private database binding
binding.create identifies the exact source service, target database and private environment alias. Its supported access\_mode is private\_runtime. The alias must be a valid private uppercase environment name, such as DATABASE\_URL.
Existing controllers deliver the database connection configuration to the service runtime. Do not ask the agent to reveal, copy into source code or return the connection string. Public build aliases and browser-exposed prefixes are rejected.
private\_runtime describes credential delivery. It does not create a separate SQL user or enforce per-consumer read-only/write roles. read\_only, read\_write and public\_build are unsupported for this direct binding action.
## Keep permission and execution separate
The initial client login may grant reads only. A connection cannot create resources until the owner explicitly authorizes the required action scopes through a new consent. Follow the client guide to authorize additional actions.
Each proposal retains its configuration and affected resource revisions. Review the exact proposal in the owner interface; the external client cannot approve itself. Changed targets require a new valid proposal.
A successful proposal or approval does not mean the database is provisioned or the release is healthy. Inspect controller\_operations and the resource readiness evidence. Build success and deployment success remain distinct.
## Reconnect, retry and partial failure
Retain each idempotency key with its exact request. After a lost response, retry the same request/key or inspect the recorded operation. Do not issue a different key merely because the response was lost.
A new client session can rediscover authorized resources and current work. Use canonical identities and recorded results to continue; do not match resources by similar names or assume an unavailable history source is empty.
Partial failures can leave useful resources. Inspect what exists before retrying. Revoking a connection removes pending authority but does not delete resources or prove an already-dispatched controller stopped. Cleanup is a separate governed request.
## Verify each application outcome
Retain the exact Application/service/database/release references, readiness outcome and application smoke-test result. A working client connection is separate from the outcome of a particular deployment.
The typed objective checks described above are new implementation work for the next release. Existing MCP connections continue to support their available actions.
## Expected result
Completion requires healthy controller evidence and an application-level PostgreSQL write/read result. Accepted configuration, approved work or HTTP 200 alone is insufficient.
## Related guides
Connect an external client, choose its access and inspect its work in StackShift.
Understand selected resources, permitted actions, owner decisions and revocation.
Follow a deployment, release or database operation alongside its activity and approval decisions.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.