This project integrates Terraform and OpenTofu with an Apache Paimon REST
Catalog. It follows the provider shape established by
apache/terraform-provider-iceberg,
but talks directly to Paimon's language-neutral REST Catalog API instead of
embedding a JVM client.
Releases use signed Apache release candidates. See the release guide for the source-vote and Registry workflow, including verification of a published version before installation.
Resources:
paimon_databasecreates, reads, updates, imports, and drops databases.paimon_tablecreates, reads, imports, evolves supported table fields, updates options/comments, and drops managed tables.paimon_permissiongrants, reads, imports, replaces mutable assignment content, and revokes direct catalog permissions.paimon_row_filtermanages one principal's row filter on a table.paimon_column_maskmanages one principal's mask on a table column.
Data sources:
paimon_databasereads a database and its server metadata.paimon_tablereads a table schema, keys, options, and server metadata.
terraform {
required_providers {
paimon = {
source = "apache/paimon"
}
}
}
provider "paimon" {
uri = "http://localhost:8080"
warehouse = "default"
token_provider = "bear"
token = var.paimon_token
}
resource "paimon_database" "analytics" {
name = "analytics"
options = {
owner = "data-platform"
}
}
resource "paimon_table" "events" {
database = paimon_database.analytics.name
name = "events"
fields = [
{
name = "event_id"
type = "BIGINT"
nullable = false
},
{
name = "event_time"
type = "TIMESTAMP(3)"
},
{
name = "payload"
type = "STRING"
}
]
partition_keys = []
options = {
"primary-key" = "event_id"
"bucket" = "4"
}
comment = "Events managed by Terraform"
}
resource "paimon_permission" "analyst_read" {
resource_type = "TABLE"
database = paimon_table.events.database
table = paimon_table.events.name
access = "SELECT"
principal = "role:analyst"
}Only the REST metastore is in scope. Filesystem, Hive, and JDBC catalogs are not accessed directly because Terraform needs a stable remote control-plane contract; Paimon's REST OpenAPI provides that contract.
Permission, row-filter, and column-mask resources use Paimon's experimental REST management API. Principal lifecycle and group or role membership remain server responsibilities.
Table replacements are blocked unless allow_replacement = true.
Protect retained production data with Terraform's prevent_destroy lifecycle
rule as shown in the production example.
Row-filter and column-mask content updates require
allow_non_atomic_update = true during a maintenance window because the REST
API cannot update a policy atomically. Import existing policies explicitly.
The production validation guide distinguishes local protocol coverage from real REST/DLF and query-engine validation.
terraform import paimon_database.analytics analytics
terraform import paimon_table.events analytics.events
terraform import paimon_permission.analyst_read \
'resource_type=TABLE&database=analytics&table=events&access=SELECT&principal=role%3Aanalyst'Use the Go version specified in go.mod or a newer compatible version.
make check
make check-docs
make test-acceptancemake check includes the documentation schema check. make check-docs runs it
on its own: every registered provider, resource, and data-source field must have
a reference entry with its actual type, required/optional/computed mode, and
sensitive flag. Update the reference descriptions when changing defaults,
validation, or lifecycle behavior; those semantics still require review.
See docs/index.md for the provider configuration and links to
the complete resource and data-source field references.
See the API contract for the current resource model and
experimental management boundary. Primary keys use options["primary-key"];
primary_keys is a computed output.
