Skip to content

Commit a77f89f

Browse files
AmanVarshney01AmanVarshney01
authored
docs: IaC guides (Terraform, Pulumi, Alchemy) (#7474)
* docs(postgres): add IaC guides (Terraform, Pulumi, Alchemy) * docs(postgres): spell out Infrastructure as Code
1 parent ce2afbf commit a77f89f

6 files changed

Lines changed: 605 additions & 1 deletion

File tree

‎cSpell.json‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -128,7 +128,9 @@
128128
"Treatos",
129129
"Svetlana",
130130
"Queenie",
131-
"Linktree"
131+
"Linktree",
132+
"Pulumi",
133+
"buildpack"
132134
],
133135
"ignoreWords": [
134136
"Aiven",

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

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
---
2+
title: 'Terraform'
3+
metaTitle: 'Manage Prisma Postgres with Terraform'
4+
metaDescription: 'Provision and manage Prisma Postgres projects, databases, and connections using Terraform.'
5+
tocDepth: 3
6+
toc: true
7+
---
8+
9+
Use the [Prisma Postgres Terraform provider](https://registry.terraform.io/providers/prisma/prisma-postgres/latest) to manage projects, databases, and connections with code.
10+
11+
## Conceptual model
12+
13+
Terraform is a desired-state engine:
14+
15+
- You declare the target infrastructure in `.tf` files.
16+
- Terraform computes a plan (`terraform plan`) by comparing config vs current state.
17+
- Terraform applies only the required changes (`terraform apply`) and records the result in state.
18+
19+
For Prisma Postgres, this gives a predictable workflow for creating projects, databases, and connections across environments.
20+
21+
## When to use Terraform
22+
23+
Terraform is a strong fit when:
24+
25+
- You already manage infrastructure in Terraform and want one workflow.
26+
- You prefer explicit `plan` output before applying changes.
27+
- Your team standardizes on HCL modules and Terraform state backends.
28+
29+
## What you can manage
30+
31+
The provider currently supports:
32+
33+
- `prisma-postgres_project`
34+
- `prisma-postgres_database`
35+
- `prisma-postgres_connection`
36+
- `prisma-postgres_regions` data source
37+
38+
## Prerequisites
39+
40+
- [Terraform](https://developer.hashicorp.com/terraform/install) `>= 1.0`
41+
- A Prisma account and workspace in [Prisma Console](https://console.prisma.io)
42+
- A Prisma service token (see [Management API authentication docs](/postgres/introduction/management-api#service-tokens))
43+
44+
## 1. Set your service token
45+
46+
Set your token as an environment variable:
47+
48+
```terminal
49+
export PRISMA_SERVICE_TOKEN="prsc_your_token_here"
50+
```
51+
52+
## 2. Create `main.tf`
53+
54+
Create the following Terraform configuration:
55+
56+
```hcl file=main.tf
57+
terraform {
58+
required_providers {
59+
prisma-postgres = {
60+
source = "prisma/prisma-postgres"
61+
}
62+
}
63+
}
64+
65+
provider "prisma-postgres" {}
66+
67+
resource "prisma-postgres_project" "main" {
68+
name = "my-app"
69+
}
70+
71+
resource "prisma-postgres_database" "production" {
72+
project_id = prisma-postgres_project.main.id
73+
name = "production"
74+
region = "us-east-1"
75+
}
76+
77+
resource "prisma-postgres_connection" "api" {
78+
database_id = prisma-postgres_database.production.id
79+
name = "api-key"
80+
}
81+
82+
output "connection_string" {
83+
value = prisma-postgres_connection.api.connection_string
84+
sensitive = true
85+
}
86+
87+
output "direct_url" {
88+
value = prisma-postgres_database.production.direct_url
89+
sensitive = true
90+
}
91+
```
92+
93+
## 3. Initialize and apply
94+
95+
Initialize your working directory:
96+
97+
```terminal
98+
terraform init
99+
```
100+
101+
Review and apply:
102+
103+
```terminal
104+
terraform plan
105+
terraform apply
106+
```
107+
108+
After apply, retrieve values:
109+
110+
```terminal
111+
terraform output -raw connection_string
112+
terraform output -raw direct_url
113+
```
114+
115+
## 4. Clean up (optional)
116+
117+
```terminal
118+
terraform destroy
119+
```
120+
121+
## Optional: discover available regions
122+
123+
If you want to select regions dynamically:
124+
125+
```hcl
126+
data "prisma-postgres_regions" "available" {}
127+
128+
output "available_regions" {
129+
value = [
130+
for r in data.prisma-postgres_regions.available.regions : "${r.id} (${r.name})"
131+
if r.status == "available"
132+
]
133+
}
134+
```
135+
136+
## Production notes
137+
138+
- Store Terraform state in a secure remote backend (for example, S3 + DynamoDB, Terraform Cloud, etc.).
139+
- Treat state as sensitive: even with `sensitive = true`, secret values are still stored in state.
140+
- Keep `PRISMA_SERVICE_TOKEN` in your secret manager or CI secrets, not in code.
141+
- Use separate Terraform workspaces or stacks for `dev`, `staging`, and `prod`.
142+
- Rotate credentials intentionally when required by replacing connection resources.
143+
144+
## Import existing resources
145+
146+
You can import existing resources into state:
147+
148+
```terminal
149+
terraform import prisma-postgres_project.main <project-id>
150+
terraform import prisma-postgres_database.production <database-id>
151+
terraform import prisma-postgres_connection.api <database-id>,<connection-id>
152+
```
153+
154+
Credentials are only returned at creation time and cannot be recovered after import.
155+
156+
## Common troubleshooting
157+
158+
### Missing token
159+
160+
If provider configuration fails with a missing token error, confirm `PRISMA_SERVICE_TOKEN` is set in the same shell session running Terraform.
161+
162+
### Region issues
163+
164+
If create fails for a region value, use `prisma-postgres_regions` to list currently available regions for your workspace.
165+
166+
### Authorization failures
167+
168+
If you receive authorization errors, verify your service token belongs to the expected workspace and has permission to create projects and databases.
169+
170+
## References
171+
172+
- [Prisma Postgres provider on Terraform Registry](https://registry.terraform.io/providers/prisma/prisma-postgres/latest)
173+
- [Provider configuration](https://registry.terraform.io/providers/prisma/prisma-postgres/latest/docs)
174+
- [Project resource](https://registry.terraform.io/providers/prisma/prisma-postgres/latest/docs/resources/project)
175+
- [Database resource](https://registry.terraform.io/providers/prisma/prisma-postgres/latest/docs/resources/database)
176+
- [Connection resource](https://registry.terraform.io/providers/prisma/prisma-postgres/latest/docs/resources/connection)
177+
- [Regions data source](https://registry.terraform.io/providers/prisma/prisma-postgres/latest/docs/data-sources/regions)

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

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
---
2+
title: 'Pulumi'
3+
metaTitle: 'Manage Prisma Postgres with Pulumi'
4+
metaDescription: 'Provision and manage Prisma Postgres with Pulumi using the Prisma Terraform provider bridge.'
5+
tocDepth: 3
6+
toc: true
7+
---
8+
9+
Use Pulumi with the Prisma Postgres Terraform provider through the Pulumi Terraform bridge.
10+
11+
This is the currently supported path for managing Prisma Postgres from Pulumi.
12+
13+
## Conceptual model
14+
15+
Pulumi lets you define infrastructure with a general-purpose language, but still deploys declaratively:
16+
17+
- You write resource code in TypeScript.
18+
- Pulumi builds a dependency graph and previews changes (`pulumi preview`/`pulumi up`).
19+
- Stack state tracks what exists, including secret outputs.
20+
21+
In this guide, Pulumi consumes the Prisma Terraform provider through a generated SDK, so you get typed resources while reusing the same provider capabilities.
22+
23+
## When to use Pulumi
24+
25+
Pulumi is a strong fit when:
26+
27+
- You want infrastructure and application code in the same language.
28+
- You prefer typed APIs and IDE support over HCL.
29+
- You already use Pulumi stacks for environment management.
30+
31+
## Prerequisites
32+
33+
- [Pulumi CLI](https://www.pulumi.com/docs/iac/download-install/)
34+
- A Pulumi TypeScript project (create one with `pulumi new typescript`)
35+
- A Prisma service token (see [Management API authentication docs](/postgres/introduction/management-api#service-tokens))
36+
37+
## 1. Optional: use Bun for dependency installs
38+
39+
If you want Pulumi to use Bun in this project, set this in `Pulumi.yaml`:
40+
41+
```yaml file=Pulumi.yaml
42+
runtime:
43+
name: nodejs
44+
options:
45+
packagemanager: bun
46+
```
47+
48+
## 2. Add the Prisma Postgres provider package
49+
50+
From your Pulumi project directory, run:
51+
52+
```terminal
53+
pulumi package add terraform-provider registry.terraform.io/prisma/prisma-postgres 0.2.0
54+
```
55+
56+
This command:
57+
58+
- Generates a local SDK in `sdks/prisma-postgres`
59+
- Adds `packages.prisma-postgres` metadata to `Pulumi.yaml`
60+
- Adds `@pulumi/prisma-postgres` to `package.json` as a local file dependency
61+
62+
### Alternative: local provider binary
63+
64+
If you are developing the provider locally, you can also add it from a local binary path:
65+
66+
```terminal
67+
pulumi package add terraform-provider /absolute/path/to/terraform-provider-prisma-postgres
68+
```
69+
70+
For most users, the registry form in step 2 is the recommended approach.
71+
72+
## 3. Configure authentication
73+
74+
Use one of these methods:
75+
76+
### Option A: environment variable
77+
78+
```terminal
79+
export PRISMA_SERVICE_TOKEN="prsc_your_token_here"
80+
```
81+
82+
### Option B: Pulumi config secret
83+
84+
```terminal
85+
pulumi config set prisma-postgres:serviceToken "prsc_your_token_here" --secret
86+
```
87+
88+
## 4. Define resources in `index.ts`
89+
90+
```ts file=index.ts
91+
import * as pulumi from "@pulumi/pulumi";
92+
import * as prismaPostgres from "@pulumi/prisma-postgres";
93+
94+
const project = new prismaPostgres.Project("project", {
95+
name: "my-app",
96+
});
97+
98+
const database = new prismaPostgres.Database("database", {
99+
projectId: project.id,
100+
name: "production",
101+
region: "us-east-1",
102+
});
103+
104+
const connection = new prismaPostgres.Connection("connection", {
105+
databaseId: database.id,
106+
name: "api-key",
107+
});
108+
109+
const availableRegions = prismaPostgres.getRegionsOutput().regions.apply((regions) =>
110+
regions.filter((r) => r.status === "available").map((r) => `${r.id} (${r.name})`)
111+
);
112+
113+
export const projectId = project.id;
114+
export const databaseId = database.id;
115+
export const connectionString = pulumi.secret(connection.connectionString);
116+
export const directUrl = pulumi.secret(database.directUrl);
117+
export const regions = availableRegions;
118+
```
119+
120+
## 5. Deploy
121+
122+
```terminal
123+
pulumi up
124+
```
125+
126+
To read secret outputs:
127+
128+
```terminal
129+
pulumi stack output connectionString --show-secrets
130+
pulumi stack output directUrl --show-secrets
131+
```
132+
133+
## 6. Clean up
134+
135+
```terminal
136+
pulumi destroy
137+
```
138+
139+
## Production notes
140+
141+
- Store Pulumi state in a managed backend (Pulumi Cloud, S3-compatible backend, etc.).
142+
- Keep service tokens in Pulumi secrets/config or your secret manager, never in source files.
143+
- The generated SDK is a local dependency (`file:sdks/prisma-postgres`), so keep it available in CI/CD.
144+
- Pin the Terraform provider version in `pulumi package add` for reproducible deployments.
145+
146+
## Common troubleshooting
147+
148+
### Package add failed
149+
150+
Confirm you're running the command inside a Pulumi project directory containing `Pulumi.yaml`.
151+
152+
### Missing credentials
153+
154+
If provider auth fails, verify either `PRISMA_SERVICE_TOKEN` is set or `prisma-postgres:serviceToken` is configured for the current stack.
155+
156+
### SDK not found in CI
157+
158+
If CI cannot resolve `@pulumi/prisma-postgres`, make sure `sdks/prisma-postgres` exists in the workspace or rerun `pulumi package add` during CI setup.
159+
160+
## References
161+
162+
- [Pulumi package add](https://www.pulumi.com/docs/iac/cli/commands/pulumi_package_add/)
163+
- [Using any Terraform provider in Pulumi](https://www.pulumi.com/docs/iac/concepts/providers/any-terraform-provider/)
164+
- [Prisma Postgres provider on Terraform Registry](https://registry.terraform.io/providers/prisma/prisma-postgres/latest)
165+
- [Prisma Postgres Terraform provider source](https://github.com/prisma/terraform-provider-prisma-postgres)

0 commit comments

Comments
 (0)