Terraform Provider

Use the VeloDB Terraform provider to create and manage VeloDB Cloud warehouses, compute clusters, network access, PrivateLink registrations, and connection metadata through the VeloDB Cloud Management API. Use it when you want to manage these resources in version-controlled Terraform configuration.

The provider manages VeloDB Cloud control-plane resources. It does not manage SQL databases, tables, or warehouse users.

Before you begin

• Install Terraform 1.5 or later. The import example on this page uses the Terraform import block introduced in Terraform 1.5.
• Create an API key with an organization role that can manage the resources in your configuration. API keys inherit the permissions of their selected organization role.
• Store the API key and administrator password in an approved secrets manager. Do not commit either value to Terraform configuration, variable files, or source control.

Step 1: Create an API key

For instructions, see API Keys.

Store the key in an environment variable, not in Terraform files or source control:

export VELODB_API_KEY='sk-...'

Step 2: Override the API host (optional)

The provider uses api.velodb.cloud by default. Set VELODB_HOST only when VeloDB Cloud Support provides a different Management API host:

export VELODB_HOST='api.velodb.cloud'

Note:

host is a bare hostname. Do not include https://. The provider adds it automatically.

Step 3: Configure and initialize Terraform

Create a versions.tf file that declares the provider:

terraform {
  required_version = ">= 1.5.0"

  required_providers {
    velodb = {
      source  = "velodb/velodb"
      version = "~> 1.1"
    }
  }
}

provider "velodb" {}

The provider reads its API key from the environment variable that you set in the previous step. It also reads VELODB_HOST when you need to override the default host. Initialize the working directory before you add or apply resources:

terraform init

If an existing working directory uses an earlier locked provider version, run terraform init -upgrade to update it within the configured version constraint.

Step 4: Plan and apply changes

Add one or more resources from the examples below. Before you create a warehouse, provide the admin_password variable through your CI/CD secret store or another approved secret-injection mechanism. Terraform marks this value as sensitive, but it stores the value in state so it can detect password rotation. Protect remote state accordingly.

Review the proposed changes before you apply them.

Warning:

Creating warehouses and clusters can incur charges. Before you apply a configuration, review its resources and expected usage.

terraform plan
terraform apply

After a successful apply, use terraform show to review the recorded state. Changes made outside Terraform can cause drift. Run terraform plan before each change to identify drift and proposed updates.

Examples

Create a SaaS warehouse with an initial compute cluster

resource "velodb_warehouse" "analytics" {
  name            = "analytics"
  deployment_mode = "SaaS"
  cloud_provider  = "aws"
  region          = "us-east-1"
  admin_password  = var.admin_password

  initial_cluster {
    zone         = "us-east-1a"
    compute_vcpu = 4
    cache_gb     = 100

    auto_pause {
      enabled              = true
      idle_timeout_minutes = 30
    }
  }
}

variable "admin_password" {
  type        = string
  description = "Administrator password for the new warehouse."
  sensitive   = true
}

Add a compute cluster

resource "velodb_cluster" "etl" {
  warehouse_id  = velodb_warehouse.analytics.id
  name          = "etl"
  cluster_type  = "COMPUTE"
  zone          = "us-east-1a"
  compute_vcpu  = 8
  cache_gb      = 200
  desired_state = "running"
}

Read connection information for applications and automation

data "velodb_warehouse_connections" "analytics" {
  warehouse_id = velodb_warehouse.analytics.id
}

output "jdbc_urls" {
  value = [
    for ep in data.velodb_warehouse_connections.analytics.public_endpoints :
    ep.url if ep.protocol == "jdbc"
  ]
}

Import an existing BYOC (Bring Your Own Cloud) warehouse

import {
  to = velodb_warehouse.byoc
  id = "AWVA7PYB"
}

resource "velodb_warehouse" "byoc" {
  name            = "test_cli"
  deployment_mode = "BYOC"
  cloud_provider  = "aws"
  region          = "us-east-1"
}

Resources

Resource	Purpose
velodb_warehouse	Create, update, and delete SaaS warehouses; import and read existing BYOC warehouses.
velodb_cluster	Manage COMPUTE clusters inside a warehouse, including resize, pause, resume, and reboot.
velodb_warehouse_public_access_policy	Manage public endpoint access policy and CIDR allowlists.
velodb_warehouse_private_endpoint	Register and describe inbound PrivateLink endpoints for warehouse access.
velodb_private_link_endpoint_service	Register external endpoint services that VeloDB Cloud can access through PrivateLink.

Data sources

Data source	Purpose
velodb_warehouses	List warehouses by ID, name, cloud provider, region, or deployment mode.
velodb_clusters	List clusters in a warehouse by ID, name, status, type, or billing model.
velodb_warehouse_connections	Read public/private endpoints, compute clusters, observer groups, and PrivateLink service names.
velodb_warehouse_versions	List valid warehouse upgrade target version IDs.
velodb_private_link_endpoint_services	List outbound PrivateLink endpoint services and connected endpoints.

Limitations and considerations

• BYOC warehouses can be imported and read, but the provider does not create new BYOC warehouses.
• velodb_cluster manages COMPUTE clusters only. SQL and OBSERVER cluster types are blocked at plan time.
• CPU and cache resize are applied one dimension at a time. When increasing compute_vcpu, set cache_gb to the minimum for the new CPU size, then apply any additional cache-only change in a later run.
• admin_password is write-only in the API and is stored in Terraform state as a sensitive value so Terraform can detect password rotation. Restrict access to state and encrypt it at rest.

Clean up

When you no longer need resources created for testing, first review the proposed deletions:

terraform plan -destroy

Run terraform destroy only after you confirm that every planned deletion is intended. Destroying a managed warehouse permanently removes its clusters, resources, and data.