From 7eb9e24a63443b45f088f07cd4f35ea5d648a474 Mon Sep 17 00:00:00 2001 From: Amine Date: Wed, 3 Jun 2026 11:45:58 +0800 Subject: [PATCH 1/3] docs: add Terraform provider documentation and update overview --- docs.json | 1 + tools/overview.mdx | 3 + tools/terraform.mdx | 167 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 171 insertions(+) create mode 100644 tools/terraform.mdx diff --git a/docs.json b/docs.json index c81b5787..5ecf9ca3 100644 --- a/docs.json +++ b/docs.json @@ -488,6 +488,7 @@ "pages": [ "tools/overview", "tools/cli", + "tools/terraform", "tools/powersync-dashboard", "tools/diagnostics-client", "tools/local-development", diff --git a/tools/overview.mdx b/tools/overview.mdx index 0f00bf13..687e40c5 100644 --- a/tools/overview.mdx +++ b/tools/overview.mdx @@ -12,6 +12,9 @@ sidebarTitle: Overview Manage PowerSync Cloud and self-hosted instances from the command line. + + Manage PowerSync Cloud projects and instances as infrastructure-as-code. + Web app to inspect and debug syncing. Works with both cloud and self-hosted PowerSync Service instances. diff --git a/tools/terraform.mdx b/tools/terraform.mdx new file mode 100644 index 00000000..60fab587 --- /dev/null +++ b/tools/terraform.mdx @@ -0,0 +1,167 @@ +--- +title: "Terraform Provider" +description: Manage PowerSync Cloud projects and instances as infrastructure-as-code. +--- + +Terraform is a tool for managing infrastructure as code. You describe the desired state in HCL, run `terraform apply`, and Terraform calls the relevant APIs to provision and manage your infrastructure. The PowerSync Terraform provider brings PowerSync Cloud into that workflow. + +Use it to: + +- Provision PowerSync in the same `terraform apply` that creates your database and other cloud resources. +- Define dev, staging, and production environments once in version-controlled config rather than configuring each manually in the dashboard. +- Review changes to sync configuration, replication connections, and authentication settings as Terraform plan diffs in pull requests. + +This guide covers PowerSync Cloud only. For self-hosted deployments, see the [self-hosting overview](/maintenance-ops/self-hosting/overview). + + +**Prerequisites** + +- Terraform 1.5 or later +- A PowerSync Cloud account +- A source database. The examples in this guide use Postgres via Supabase. If your database is also managed by Terraform, you can reference it in the same configuration. + + +## Get a Personal Access Token + +The provider authenticates using a personal access token. In the dashboard, go to **Account → Access Tokens** and create a new token. Treat it like a password. It grants account access. + +Set it as an environment variable before running any Terraform commands: + +```sh +export PS_PAT_TOKEN="jpt_..." +``` + +The provider reads this environment variable automatically. + +## Find Your Organization ID + +Your organization ID appears in the dashboard URL. When you are on the organization home page, the URL contains a hex segment like `/orgs/64b3f8e1a2c4d5e6f7080912/`. That segment is your organization ID. + +## Configure the Provider + +Create a new directory and a `main.tf` file. Start with the provider declaration: + +```hcl +terraform { + required_providers { + powersync = { + source = "powersync-ja/powersync" + version = "~> 0.1.0" + } + } +} + +provider "powersync" { + # admin_token is picked up from the PS_PAT_TOKEN environment variable (recommended). + # It can also be inlined — less secure, but if inlined via a variable the value + # itself can still be passed securely through Terraform's own env vars + # (e.g. TF_VAR_ps_admin_token). + # admin_token = var.admin_token +} +``` + +Then run: + +```sh +terraform init +``` + +This downloads the provider binary from the Terraform Registry. + +## Create a Project + +Add a data source to look up your organization, then a resource to create a project: + +```hcl +data "powersync_organization" "main" { + id = "64b3f8e1a2c4d5e6f7080912" +} + +resource "powersync_project" "main" { + org_id = data.powersync_organization.main.id + name = "my-project" + region = "us" +} +``` + +The [`data "powersync_organization"`](https://registry.terraform.io/providers/powersync-ja/powersync/latest/docs/data-sources/organization) block reads your existing organization. Organizations are created when you sign up and are not managed as Terraform resources. The [`powersync_project`](https://registry.terraform.io/providers/powersync-ja/powersync/latest/docs/resources/project) resource creates a new project under it. Supported regions are `eu`, `us`, `jp`, `au`, and `br`. + +## Create an Instance + +Add the [`powersync_instance`](https://registry.terraform.io/providers/powersync-ja/powersync/latest/docs/resources/instance) resource, which wires together a replication connection, client authentication, and your sync configuration: + +```hcl +variable "replication_password" { + type = string + sensitive = true +} + +resource "powersync_instance" "main" { + org_id = data.powersync_organization.main.id + project_id = powersync_project.main.id + name = "production" + + replication_connection { + type = "postgresql" + name = "main" + hostname = "db..supabase.co" + port = 5432 + username = "powersync_role" + password = var.replication_password + database = "postgres" + sslmode = "verify-full" + } + + client_auth { + supabase = true + allow_temporary_tokens = true + } + + sync_config_content = <<-YAML + config: + edition: 3 + streams: + todos: + auto_subscribe: true + query: SELECT * FROM todos + YAML +} +``` + + +You can manage your Supabase project with Terraform too, you can provision the database and PowerSync instance together in the same configuration. See the [Supabase Terraform provider](https://supabase.com/docs/guides/deployment/terraform). + + +`replication_password` is a Terraform variable. Pass its value via the environment so it never appears in plain text in your config or state files. + +The `sync_config_content` field takes a Sync Streams configuration as a YAML string. For larger configs, use `file("${path.module}/sync-config.yaml")` to load the configuration from a separate file. See the [Sync Streams documentation](/sync/streams/overview) for the full configuration reference. + +## Apply + +Set the replication password, then run: + +```sh +export TF_VAR_replication_password="..." +terraform plan +terraform apply +``` + +`terraform plan` shows you exactly what Terraform will create before you commit to it. `terraform apply` creates the project and instance, then deploys it. When it completes, the instance is live. Run `terraform show` to see the full resource state including the instance URL. + +## Managing Changes + +To update your PowerSync instance, edit any value in your config and re-run `terraform plan` then `terraform apply`. Every change triggers a full redeploy. The instance ID and URL remain the same. + +## Tear Down + +```sh +terraform destroy +``` + +This removes the instance and the project. If the project contains instances created outside of Terraform, the destroy fails. Set `force_destroy = true` on `powersync_project` to override this check. + +## Next Steps + +- [Full resource and data source reference](https://registry.terraform.io/providers/powersync-ja/powersync/latest/docs) on the Terraform Registry +- [Supabase integration guide](/integrations/supabase/guide) for Supabase-specific setup: creating the `powersync_role`, configuring publications, and JWT authentication modes +- [Sync Streams overview](/sync/streams/overview) for writing the `sync_config_content` From b3c64611fc9a36630fd6c045e2fa4b2c5810fd18 Mon Sep 17 00:00:00 2001 From: Amine Date: Wed, 3 Jun 2026 15:40:25 +0800 Subject: [PATCH 2/3] doc: loosen Terraform provider version to 0.1 --- tools/terraform.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/terraform.mdx b/tools/terraform.mdx index 60fab587..eabb62d3 100644 --- a/tools/terraform.mdx +++ b/tools/terraform.mdx @@ -46,7 +46,7 @@ terraform { required_providers { powersync = { source = "powersync-ja/powersync" - version = "~> 0.1.0" + version = "~> 0.1" } } } From 2f8a9e032ec0cd6c68e7d3f3ac3c86be51e9ee91 Mon Sep 17 00:00:00 2001 From: michaelbarnes Date: Thu, 4 Jun 2026 15:02:00 -0600 Subject: [PATCH 3/3] docs: small changes and added the registry link upfront --- docs.json | 33 +++++++-------------------------- tools/terraform.mdx | 8 +++++++- 2 files changed, 14 insertions(+), 27 deletions(-) diff --git a/docs.json b/docs.json index 5ecf9ca3..40870b0c 100644 --- a/docs.json +++ b/docs.json @@ -63,15 +63,7 @@ ] }, "contextual": { - "options": [ - "copy", - "view", - "chatgpt", - "claude", - "mcp", - "cursor", - "vscode" - ] + "options": ["copy", "view", "chatgpt", "claude", "mcp", "cursor", "vscode"] }, "integrations": { "plausible": { @@ -274,9 +266,7 @@ { "group": "Tauri", "icon": "/logo/tauri_sidebar.svg", - "pages": [ - "client-sdks/reference/tauri" - ] + "pages": ["client-sdks/reference/tauri"] }, { "group": "Frameworks/Integrations", @@ -328,16 +318,12 @@ { "group": ".NET", "icon": "microsoft", - "pages": [ - "client-sdks/reference/dotnet" - ] + "pages": ["client-sdks/reference/dotnet"] }, { "group": "Rust", "icon": "rust", - "pages": [ - "client-sdks/reference/rust" - ] + "pages": ["client-sdks/reference/rust"] }, "/client-sdks/orms/overview", { @@ -398,9 +384,7 @@ }, { "group": "Advanced", - "pages": [ - "handling-writes/custom-write-checkpoints" - ] + "pages": ["handling-writes/custom-write-checkpoints"] } ] }, @@ -522,10 +506,7 @@ "resources/local-first-software", { "group": "Security & HIPAA", - "pages": [ - "resources/security", - "resources/hipaa" - ] + "pages": ["resources/security", "resources/hipaa"] }, "resources/contact-us" ] @@ -772,7 +753,7 @@ }, { "source": "/usage/sync-rules/operators-and-functions", - "destination": "/sync/supported-sql" + "destination": "/sync/supported-sql" }, { "source": "/sync/rules/supported-sql", diff --git a/tools/terraform.mdx b/tools/terraform.mdx index eabb62d3..c192f731 100644 --- a/tools/terraform.mdx +++ b/tools/terraform.mdx @@ -5,6 +5,10 @@ description: Manage PowerSync Cloud projects and instances as infrastructure-as- Terraform is a tool for managing infrastructure as code. You describe the desired state in HCL, run `terraform apply`, and Terraform calls the relevant APIs to provision and manage your infrastructure. The PowerSync Terraform provider brings PowerSync Cloud into that workflow. + + Terraform Registry + + Use it to: - Provision PowerSync in the same `terraform apply` that creates your database and other cloud resources. @@ -162,6 +166,8 @@ This removes the instance and the project. If the project contains instances cre ## Next Steps -- [Full resource and data source reference](https://registry.terraform.io/providers/powersync-ja/powersync/latest/docs) on the Terraform Registry +- [PowerSync Provider](https://registry.terraform.io/providers/powersync-ja/powersync/latest/docs) on the Terraform Registry +- [Supported source database setup](/configuration/source-db/setup.mdx) for configuring connection with the PowerSync Service +- [Connecting your client](/client-sdks/overview) to a PowerSync Service instance - [Supabase integration guide](/integrations/supabase/guide) for Supabase-specific setup: creating the `powersync_role`, configuring publications, and JWT authentication modes - [Sync Streams overview](/sync/streams/overview) for writing the `sync_config_content`