How to use Neon with SST V3

[Murderlon]

I'm deploying my app with SST and I would like to integrate it with Neon too. Unfortunately, there is no native integration and also no Pulumi provider for Neon.

How do I integrate Neon into SST? Ideally to create local branches automatically, but simple integration is also fine. Maybe Linkable can be used somehow.

Here is an example how it looks for PlanetScale:

const mysql = planetscale.getDatabaseOutput({
  name: "terminal",
  organization: "terminal",
});

const branch =
  $app.stage !== "production"
    ? new planetscale.Branch("DatabaseBranch", {
        database: mysql.name,
        organization: mysql.organization,
        name: $app.stage,
        parentBranch: "production",
      })
    : planetscale.getBranchOutput({
        name: "production",
        organization: mysql.organization,
        database: mysql.name,
      });

const password = new planetscale.Password("DatabasePassword", {
  database: mysql.name,
  organization: mysql.organization,
  branch: branch.name,
  role: "admin",
  name: `${$app.name}-${$app.stage}-credentials`,
});

export const database = new sst.Linkable("Database", {
  properties: {
    username: password.username,
    host: branch.mysqlAddress,
    password: password.plaintext,
    database: password.database,
    port: 3306,
  },
});

[manimovassagh]

There is actually a Pulumi provider for Neon now: the community-maintained pulumi-neon package (https://github.com/neon-community/pulumi-neon), which wraps the Terraform provider. Since SST v3 is built on Pulumi/Ion, you can use it directly.

Here is roughly how the integration would look:

import * as neon from "@pulumi/neon";
import { Linkable } from "sst";

const project = neon.getProjectOutput({ id: "your-neon-project-id" });

// Create a branch per stage, use main for production
const branch =
  $app.stage !== "production"
    ? new neon.Branch("DatabaseBranch", {
        projectId: project.id,
        name: $app.stage,
        parentId: project.defaultBranchId,
      })
    : neon.getBranchOutput({
        projectId: project.id,
        id: project.defaultBranchId,
      });

const endpoint = new neon.Endpoint("DatabaseEndpoint", {
  projectId: project.id,
  branchId: branch.id,
  type: "read_write",
});

const role = new neon.Role("DatabaseRole", {
  projectId: project.id,
  branchId: branch.id,
  name: `${$app.name}_${$app.stage}`,
});

export const database = new Linkable("Database", {
  properties: {
    host: endpoint.host,
    database: "neondb",
    user: role.name,
    password: role.password,
  },
});

If you do not want the Pulumi provider complexity, a simpler approach is to manage branches via the Neon API in a custom script during your deploy pipeline, and just use a plain Linkable with the connection string:

export const database = new Linkable("Database", {
  properties: {
    url: process.env.NEON_DATABASE_URL,
  },
});

The Pulumi provider approach gives you automatic branch creation/cleanup per stage, which is the real killer feature for dev/preview environments -- very similar to what you showed with PlanetScale.