Module neon 

Available on crate feature neon only.

Neon branches as an environment source (feature neon).

An instance can be bound to a branch of a Neon project. The branch then supplies what the plan’s Neon-hosted placements need (see Plan::neon_requirements): its Postgres, its object storage and the URLs of the functions deployed on it. Everything goes through the Neon CLI behind NeonControl: NeonCli runs neon, and FakeNeon (feature testing) stands in for it in tests. A pure compose environment never touches it.

• bind checks the branch against the plan’s requirements (a missing function is an error then, not at start), creates the databases and buckets it lacks, and mints a storage credential on the branch for the instance. A child branch inherits its parent’s credentials, so reusing one would leak access into every later branch; each binding mints its own, and unbind revokes it.
• NeonBranchSource is the Source an instance takes the branch’s overlay from: DATABASE_URL, DATABASE_URL_UNPOOLED, PG*, the NEON_S3_* storage coordinates and each function’s <SLUG>_FUNCTION_URL.
• Branches trestle creates (create_owned_branch) carry an ownership annotation and an expiry. Only owned branches are reset or deleted (reset_owned_branch, delete_owned_branch).

See docs/neon.md for what the CLI prints.

Structs

Branch

A branch of a Neon project.

Connection

A branch’s Postgres connection, as neon connection-string --extended prints it.

CreateBranch

How to create a branch.

FakeNeon

One Neon project in memory, behaving as the spike found the real one does (docs/neon.md): a new branch copies its parent’s functions, buckets and credentials at creation, a reset leaves functions alone, and annotations are kept. Every change is recorded (calls).

Function

A function deployed on a branch.

NeonBinding

An instance’s binding to a Neon branch: its SourceBinding config for NEON_SOURCE, written by bind. It holds no secret, only where the storage credential’s secret is kept.

NeonBranchSource

The overlay of the Neon branch an instance is bound to (its source config is a NeonBinding):

NeonCli

The Neon CLI (neon, or neonctl), run with --output json. Signed in the way the CLI is (~/.config/neon, shared with the terminal) or with NEON_API_KEY.

Storage

A branch’s object storage, as neon api /projects/<p>/branches/<b>/storage returns it.

StorageCredential

A storage credential minted on a branch: the S3 access key id is its token_id.

StorageCredentialRef

A storage credential as a binding refers to it: its id (the S3 access key id) and where its secret lives.

Enums

NeonCall

A call FakeNeon was asked to make.

NeonError

What can go wrong talking to Neon.

Constants

INSTANCE_ANNOTATION

The annotation key naming the instance a trestle-created branch was made for.

NEON_SOURCE

The name instances bind the Neon source by.

OWNER

The value of OWNER_ANNOTATION on a trestle-created branch.

OWNER_ANNOTATION

The annotation key that marks a branch as created by trestle.

Traits

NeonControl

What trestle asks of Neon, per project. NeonCli runs the Neon CLI; FakeNeon (feature testing) is an in-memory stand-in.

Functions

bind

Bind an instance to the branch name_or_id of project, for a plan that needs req:

create_owned_branch

Create a branch owned by trestle: annotated with OWNER_ANNOTATION (and the instance, when it is made for one) and expiring at expires_at.

delete_owned_branch

Delete the branch name_or_id, if trestle created it.

expires_in

An RFC 3339 timestamp ttl from now, for CreateBranch::expires_at.

find_branch

The branch name_or_id of the project.

locate_neon

Where the Neon CLI is, in order: explicit, $NEON_CLI, neon on PATH, the Homebrew prefixes and ~/.npm-global/bin, a login shell’s command -v neon, then the same for neonctl. An app started from the Finder has launchd’s PATH, which holds none of them, hence the fixed places and the login shell.

reset_owned_branch

Reset the branch name_or_id to its parent, if trestle created it.

unbind

Undo bind: revoke the binding’s storage credential, if it has one.