docs(postgres): IaC guides (Terraform, Pulumi, Alchemy)

cSpell.json

@@ -128,7 +128,9 @@
     "Treatos",
     "Svetlana",
     "Queenie",
-    "Linktree"
+    "Linktree",
+    "Pulumi",
+    "buildpack"
   ],
   "ignoreWords": [
     "Aiven",

content/250-postgres/360-iac/100-terraform.mdx

@@ -0,0 +1,177 @@
+---
+title: 'Terraform'
+metaTitle: 'Manage Prisma Postgres with Terraform'
+metaDescription: 'Provision and manage Prisma Postgres projects, databases, and connections using Terraform.'
+tocDepth: 3
+toc: true
+---
+
+Use the [Prisma Postgres Terraform provider](https://registry.terraform.io/providers/prisma/prisma-postgres/latest) to manage projects, databases, and connections with code.
+
+## Conceptual model
+
+Terraform is a desired-state engine:
+
+- You declare the target infrastructure in `.tf` files.
+- Terraform computes a plan (`terraform plan`) by comparing config vs current state.
+- Terraform applies only the required changes (`terraform apply`) and records the result in state.
+
+For Prisma Postgres, this gives a predictable workflow for creating projects, databases, and connections across environments.
+
+## When to use Terraform
+
+Terraform is a strong fit when:
+
+- You already manage infrastructure in Terraform and want one workflow.
+- You prefer explicit `plan` output before applying changes.
+- Your team standardizes on HCL modules and Terraform state backends.
+
+## What you can manage
+
+The provider currently supports:
+
+- `prisma-postgres_project`
+- `prisma-postgres_database`
+- `prisma-postgres_connection`
+- `prisma-postgres_regions` data source
+
+## Prerequisites
+
+- [Terraform](https://developer.hashicorp.com/terraform/install) `>= 1.0`
+- A Prisma account and workspace in [Prisma Console](https://console.prisma.io)
+- A Prisma service token (see [Management API authentication docs](/postgres/introduction/management-api#service-tokens))
+
+## 1. Set your service token
+
+Set your token as an environment variable:
+
+```terminal
+export PRISMA_SERVICE_TOKEN="prsc_your_token_here"
+```
+
+## 2. Create `main.tf`
+
+Create the following Terraform configuration:
+
+```hcl file=main.tf
+terraform {
+  required_providers {
+    prisma-postgres = {
+      source = "prisma/prisma-postgres"
+    }
+  }
+}
+
+provider "prisma-postgres" {}
+
+resource "prisma-postgres_project" "main" {
+  name = "my-app"
+}
+
+resource "prisma-postgres_database" "production" {
+  project_id = prisma-postgres_project.main.id
+  name       = "production"
+  region     = "us-east-1"
+}
+
+resource "prisma-postgres_connection" "api" {
+  database_id = prisma-postgres_database.production.id
+  name        = "api-key"
+}
+
+output "connection_string" {
+  value     = prisma-postgres_connection.api.connection_string
+  sensitive = true
+}
+
+output "direct_url" {
+  value     = prisma-postgres_database.production.direct_url
+  sensitive = true
+}
+```
+
+## 3. Initialize and apply
+
+Initialize your working directory:
+
+```terminal
+terraform init
+```
+
+Review and apply:
+
+```terminal
+terraform plan
+terraform apply
+```
+
+After apply, retrieve values:
+
+```terminal
+terraform output -raw connection_string
+terraform output -raw direct_url
+```
+
+## 4. Clean up (optional)
+
+```terminal
+terraform destroy
+```
+
+## Optional: discover available regions
+
+If you want to select regions dynamically:
+
+```hcl
+data "prisma-postgres_regions" "available" {}
+
+output "available_regions" {
+  value = [
+    for r in data.prisma-postgres_regions.available.regions : "${r.id} (${r.name})"
+    if r.status == "available"
+  ]
+}
+```
+
+## Production notes
+
+- Store Terraform state in a secure remote backend (for example, S3 + DynamoDB, Terraform Cloud, etc.).
+- Treat state as sensitive: even with `sensitive = true`, secret values are still stored in state.
+- Keep `PRISMA_SERVICE_TOKEN` in your secret manager or CI secrets, not in code.
+- Use separate Terraform workspaces or stacks for `dev`, `staging`, and `prod`.
+- Rotate credentials intentionally when required by replacing connection resources.
+
+## Import existing resources
+
+You can import existing resources into state:
+
+```terminal
+terraform import prisma-postgres_project.main <project-id>
+terraform import prisma-postgres_database.production <database-id>
+terraform import prisma-postgres_connection.api <database-id>,<connection-id>
+```
+
+Credentials are only returned at creation time and cannot be recovered after import.
+
+## Common troubleshooting
+
+### Missing token
+
+If provider configuration fails with a missing token error, confirm `PRISMA_SERVICE_TOKEN` is set in the same shell session running Terraform.
+
+### Region issues
+
+If create fails for a region value, use `prisma-postgres_regions` to list currently available regions for your workspace.
+
+### Authorization failures
+
+If you receive authorization errors, verify your service token belongs to the expected workspace and has permission to create projects and databases.
+
+## References
+
+- [Prisma Postgres provider on Terraform Registry](https://registry.terraform.io/providers/prisma/prisma-postgres/latest)
+- [Provider configuration](https://registry.terraform.io/providers/prisma/prisma-postgres/latest/docs)
+- [Project resource](https://registry.terraform.io/providers/prisma/prisma-postgres/latest/docs/resources/project)
+- [Database resource](https://registry.terraform.io/providers/prisma/prisma-postgres/latest/docs/resources/database)
+- [Connection resource](https://registry.terraform.io/providers/prisma/prisma-postgres/latest/docs/resources/connection)
+- [Regions data source](https://registry.terraform.io/providers/prisma/prisma-postgres/latest/docs/data-sources/regions)

content/250-postgres/360-iac/200-pulumi.mdx

@@ -0,0 +1,165 @@
+---
+title: 'Pulumi'
+metaTitle: 'Manage Prisma Postgres with Pulumi'
+metaDescription: 'Provision and manage Prisma Postgres with Pulumi using the Prisma Terraform provider bridge.'
+tocDepth: 3
+toc: true
+---
+
+Use Pulumi with the Prisma Postgres Terraform provider through the Pulumi Terraform bridge.
+
+This is the currently supported path for managing Prisma Postgres from Pulumi.
+
+## Conceptual model
+
+Pulumi lets you define infrastructure with a general-purpose language, but still deploys declaratively:
+
+- You write resource code in TypeScript.
+- Pulumi builds a dependency graph and previews changes (`pulumi preview`/`pulumi up`).
+- Stack state tracks what exists, including secret outputs.
+
+In this guide, Pulumi consumes the Prisma Terraform provider through a generated SDK, so you get typed resources while reusing the same provider capabilities.
+
+## When to use Pulumi
+
+Pulumi is a strong fit when:
+
+- You want infrastructure and application code in the same language.
+- You prefer typed APIs and IDE support over HCL.
+- You already use Pulumi stacks for environment management.
+
+## Prerequisites
+
+- [Pulumi CLI](https://www.pulumi.com/docs/iac/download-install/)
+- A Pulumi TypeScript project (create one with `pulumi new typescript`)
+- A Prisma service token (see [Management API authentication docs](/postgres/introduction/management-api#service-tokens))
+
+## 1. Optional: use Bun for dependency installs
+
+If you want Pulumi to use Bun in this project, set this in `Pulumi.yaml`:
+
+```yaml file=Pulumi.yaml
+runtime:
+  name: nodejs
+  options:
+    packagemanager: bun
+```
+
+## 2. Add the Prisma Postgres provider package
+
+From your Pulumi project directory, run:
+
+```terminal
+pulumi package add terraform-provider registry.terraform.io/prisma/prisma-postgres 0.2.0
+```
+
+This command:
+
+- Generates a local SDK in `sdks/prisma-postgres`
+- Adds `packages.prisma-postgres` metadata to `Pulumi.yaml`
+- Adds `@pulumi/prisma-postgres` to `package.json` as a local file dependency
+
+### Alternative: local provider binary
+
+If you are developing the provider locally, you can also add it from a local binary path:
+
+```terminal
+pulumi package add terraform-provider /absolute/path/to/terraform-provider-prisma-postgres
+```
+
+For most users, the registry form in step 2 is the recommended approach.
+
+## 3. Configure authentication
+
+Use one of these methods:
+
+### Option A: environment variable
+
+```terminal
+export PRISMA_SERVICE_TOKEN="prsc_your_token_here"
+```
+
+### Option B: Pulumi config secret
+
+```terminal
+pulumi config set prisma-postgres:serviceToken "prsc_your_token_here" --secret
+```
+
+## 4. Define resources in `index.ts`
+
+```ts file=index.ts
+import * as pulumi from "@pulumi/pulumi";
+import * as prismaPostgres from "@pulumi/prisma-postgres";
+
+const project = new prismaPostgres.Project("project", {
+  name: "my-app",
+});
+
+const database = new prismaPostgres.Database("database", {
+  projectId: project.id,
+  name: "production",
+  region: "us-east-1",
+});
+
+const connection = new prismaPostgres.Connection("connection", {
+  databaseId: database.id,
+  name: "api-key",
+});
+
+const availableRegions = prismaPostgres.getRegionsOutput().regions.apply((regions) =>
+  regions.filter((r) => r.status === "available").map((r) => `${r.id} (${r.name})`)
+);
+
+export const projectId = project.id;
+export const databaseId = database.id;
+export const connectionString = pulumi.secret(connection.connectionString);
+export const directUrl = pulumi.secret(database.directUrl);
+export const regions = availableRegions;
+```
+
+## 5. Deploy
+
+```terminal
+pulumi up
+```
+
+To read secret outputs:
+
+```terminal
+pulumi stack output connectionString --show-secrets
+pulumi stack output directUrl --show-secrets
+```
+
+## 6. Clean up
+
+```terminal
+pulumi destroy
+```
+
+## Production notes
+
+- Store Pulumi state in a managed backend (Pulumi Cloud, S3-compatible backend, etc.).
+- Keep service tokens in Pulumi secrets/config or your secret manager, never in source files.
+- The generated SDK is a local dependency (`file:sdks/prisma-postgres`), so keep it available in CI/CD.
+- Pin the Terraform provider version in `pulumi package add` for reproducible deployments.
+
+## Common troubleshooting
+
+### Package add failed
+
+Confirm you're running the command inside a Pulumi project directory containing `Pulumi.yaml`.
+
+### Missing credentials
+
+If provider auth fails, verify either `PRISMA_SERVICE_TOKEN` is set or `prisma-postgres:serviceToken` is configured for the current stack.
+
+### SDK not found in CI
+
+If CI cannot resolve `@pulumi/prisma-postgres`, make sure `sdks/prisma-postgres` exists in the workspace or rerun `pulumi package add` during CI setup.
+
+## References
+
+- [Pulumi package add](https://www.pulumi.com/docs/iac/cli/commands/pulumi_package_add/)
+- [Using any Terraform provider in Pulumi](https://www.pulumi.com/docs/iac/concepts/providers/any-terraform-provider/)
+- [Prisma Postgres provider on Terraform Registry](https://registry.terraform.io/providers/prisma/prisma-postgres/latest)
+- [Prisma Postgres Terraform provider source](https://github.com/prisma/terraform-provider-prisma-postgres)