Choosing a warehouse
A newly registered Platinur account has no warehouse bound. The operator opens Configuration and selects a warehouse engine from the selector. Filling in the required connection details and clicking Test connection verifies reachability; a successful test binds the engine to the account.
Until a warehouse is bound, source loading and modeling are unavailable.
Supported engines
| Engine | Status | Notes |
|---|
| ClickHouse | GA | Connect your own cluster or ClickHouse Cloud service. |
| Snowflake | Beta | Key-pair (RSA) authentication — password sign-in is blocked by Snowflake MFA. |
| BigQuery | Beta | Service-account JSON + dataset location. |
| Databricks | Beta | Unity Catalog. Personal-access token. |
| Redshift | Beta | User/password or IAM credentials. |
Microsoft Synapse and Microsoft Fabric are not supported.
Choosing an engine is a one-time decision
Once a successful test binds the engine kind, the engine kind is fixed for that account. Attempting to save a different engine kind returns HTTP 409 with the message “reset the account to choose a different one.”
The connection details and credentials for the bound engine remain editable at any time — change a hostname, rotate a key, or swap service-account credentials without affecting the binding.
Per-engine credentials
Credentials are stored as secret references inside Platinur’s secret store, never written to YAML or logs. Fields marked secret are encrypted at rest and never echoed back through the portal.
ClickHouse
You need: a reachable ClickHouse cluster (self-managed or ClickHouse Cloud) and a user with the permissions below. Supply the hostname and credentials in the form; Platinur connects to your cluster over the network, with TLS by default.
| Form field | What it is | How to obtain it |
|---|
| Host | Hostname of the ClickHouse server, no scheme or port | Your cluster hostname, or the endpoint from ClickHouse Cloud service details |
| HTTP port | HTTP(S) interface port (default 8443 with TLS, 8123 without) | Read from cluster config; ClickHouse Cloud defaults to 8443 |
| Native port | Native TCP interface port (default 9440 with TLS, 9000 without) | Read from cluster config; ClickHouse Cloud defaults to 9440 |
| Username | ClickHouse login name (default default) | Create a dedicated user in ClickHouse or use default |
| Password (secret) | Password for the ClickHouse user | Create a dedicated user and password in ClickHouse, or use an existing one |
| Analytics database | Target database Platinur writes dbt output into (default analytics) | Create this database, or grant CREATE DATABASE so Platinur creates it |
| Raw database | Fallback raw schema name when no source-specific schema applies (default raw) | Leave as raw; Platinur creates it if it does not exist |
| Use TLS | Enable HTTPS/TLS for all connections | Enable for ClickHouse Cloud and any TLS-terminated cluster |
The ClickHouse user needs CREATE DATABASE on the server and full DDL/DML on Platinur’s output databases (raw, stg_*, prod_*, and *_validation), plus SELECT on source databases it should model from. For source data loaded outside Platinur, see External Source Schemas.
Network access. If your cluster sits behind a firewall or IP allowlist, allowlist Platinur’s egress IP (available from support) on both configured ports.
ClickHouse Cloud. The defaults match ClickHouse Cloud: HTTPS on 8443, native TLS on 9440, and Use TLS enabled. Use the hostname and credentials from your service’s connection details. Trial and development services idle when unused, and the first query after idling is slow while the service wakes — a sluggish first connection test or source load after a quiet period is expected.
Snowflake
You need: a Snowflake account, a dedicated virtual warehouse, a dedicated database, a custom role, and a service user. Authenticate the service user with an RSA key pair — the private key is stored as a secret ref. Password sign-in is not supported (Snowflake enforces MFA for it). Platinur creates and manages schemas inside the database you supply.
Use key-pair authentication, not a password. Snowflake now enforces multi-factor
authentication for password sign-in. A non-interactive service like Platinur cannot answer an
MFA challenge, so password auth fails with Multi-factor authentication is required for this account. Enrolling a passkey on your own user does not help — it applies to your human login,
not the service user, and a headless connection cannot complete MFA regardless. Authenticate the
service user with an RSA key pair (below), which is exempt from MFA. Optionally mark it a
service-type user so it cannot use a password at all: ALTER USER PLATINUR_SVC SET TYPE = SERVICE.
| Form field | What it is | How to obtain it |
|---|
| Account identifier | Snowflake account locator (e.g. ORGNAME-ACCOUNTNAME) | Snowsight → Account menu (bottom-left) → Account details; copy the org-account slug |
| User | Snowflake login name for the service user | Create — see provisioning snippet below (PLATINUR_SVC) |
| Private key (PEM) (secret, required) | Full PEM-encoded PKCS#8 RSA private key | Create — generated with openssl (unencrypted); paste the complete file including header and footer lines |
| Role | Snowflake role Platinur assumes for all operations | Create — see provisioning snippet below (PLATINUR_ROLE) |
| Warehouse | Virtual warehouse used for queries and dbt runs | Create — see provisioning snippet below (PLATINUR_WH) |
| Database | Database Platinur builds all schemas into | Create — see provisioning snippet below (PLATINUR) |
| Default schema | Starting schema within the database (default public) | Leave as public; Platinur creates layer schemas (stg_staging, stg_dw, etc.) automatically |
Account identifier format. The modern org-account form ORGNAME-ACCOUNTNAME works directly and is preferred. On a legacy account without an org slug, use the locator form <locator>.<region>.<cloud> visible in Snowsight → Account details.
Key-pair auth. Generate a PKCS#8 private key and extract the public key:
# Generate an unencrypted PKCS#8 RSA private key
openssl genrsa 2048 | openssl pkcs8 -topk8 -nocrypt -out platinur_rsa_key.p8
# Extract the matching public key
openssl rsa -in platinur_rsa_key.p8 -pubout -out platinur_rsa_key.pub
Register the public key on the Snowflake user (run as a Snowflake user admin):
ALTER USER PLATINUR_SVC
SET RSA_PUBLIC_KEY = '<contents of platinur_rsa_key.pub, without the BEGIN/END header lines>';
Paste the full contents of platinur_rsa_key.p8 (header, body, and footer) into the Private key (PEM) field.
Provisioning snippet (run as ACCOUNTADMIN or SYSADMIN):
-- Virtual warehouse
CREATE WAREHOUSE IF NOT EXISTS PLATINUR_WH
WAREHOUSE_SIZE = 'X-SMALL'
AUTO_SUSPEND = 60
AUTO_RESUME = TRUE
INITIALLY_SUSPENDED = TRUE;
-- Target database
CREATE DATABASE IF NOT EXISTS PLATINUR;
-- Dedicated role
CREATE ROLE IF NOT EXISTS PLATINUR_ROLE;
-- Service user — key-pair only (no password). TYPE = SERVICE marks it a non-human
-- automation user that cannot use a password or MFA. Register its public key with the
-- `ALTER USER ... SET RSA_PUBLIC_KEY` statement from the "Key-pair auth" step above.
CREATE USER IF NOT EXISTS PLATINUR_SVC
TYPE = SERVICE
DEFAULT_ROLE = PLATINUR_ROLE
DEFAULT_WAREHOUSE = PLATINUR_WH;
-- Warehouse usage
GRANT USAGE ON WAREHOUSE PLATINUR_WH TO ROLE PLATINUR_ROLE;
-- Full ownership of the target database so Platinur can manage schemas
GRANT OWNERSHIP ON DATABASE PLATINUR TO ROLE PLATINUR_ROLE COPY CURRENT GRANTS;
-- Read access to each source database Platinur should model from.
-- Repeat the three lines below for every source database.
-- GRANT USAGE ON DATABASE <your_source_db> TO ROLE PLATINUR_ROLE;
-- GRANT USAGE ON ALL SCHEMAS IN DATABASE <your_source_db> TO ROLE PLATINUR_ROLE;
-- GRANT SELECT ON ALL TABLES IN DATABASE <your_source_db> TO ROLE PLATINUR_ROLE;
-- Bind role to user
GRANT ROLE PLATINUR_ROLE TO USER PLATINUR_SVC;
Form field mapping:
PLATINUR_SVC → User
- Contents of
platinur_rsa_key.p8 → Private key (PEM)
PLATINUR_ROLE → Role
PLATINUR_WH → Warehouse
PLATINUR → Database
- Org-account slug from Snowsight → Account identifier
BigQuery
You need: a GCP project, a service account with BigQuery IAM roles, a downloaded JSON key file, and a GCS bucket for dlt load staging. The entire JSON key is stored as a secret ref. All BigQuery datasets are created in the location you specify and cannot be moved after creation.
| Form field | What it is | How to obtain it |
|---|
| Project ID | GCP project that owns the BigQuery datasets | Read — GCP console project selector, or gcloud config get-value project |
| Default dataset | BigQuery dataset used as the default dbt target (default platinur) | Create — Platinur creates it on first run; pick a name meaningful to your project |
| Location | Dataset region, e.g. US, EU, us-central1 | Choose — must match all datasets and the GCS staging bucket; immutable after creation |
| Service-account key (JSON) (secret) | Full service-account JSON key file contents | Create — download after creating the service account; see snippet below |
| Max bytes billed / query | Per-query cost guard in bytes (default 1 GB) | Set based on your BigQuery budget; raise for large dbt models |
| Staging GCS bucket URL | gs://bucket/prefix dlt writes load files here before BigQuery ingest | Create — provision a GCS bucket in the same location; required to run Integrations source loads |
Location is immutable. Platinur creates every dataset (output layers, raw, and the validation sandbox) in the location you enter here. Cross-location joins fail immediately. Choose a single region or multi-region value and create your GCS staging bucket in the same location.
Provisioning snippet:
PROJECT_ID="<project-id>"
SA_NAME="platinur-svc"
SA_EMAIL="${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com"
STAGING_BUCKET="gs://my-platinur-staging"
# Create the service account
gcloud iam service-accounts create "${SA_NAME}" \
--display-name="Platinur service account" \
--project="${PROJECT_ID}"
# BigQuery: create/update datasets and tables
gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
--member="serviceAccount:${SA_EMAIL}" \
--role="roles/bigquery.dataEditor"
# BigQuery: run queries and load jobs
gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
--member="serviceAccount:${SA_EMAIL}" \
--role="roles/bigquery.jobUser"
# GCS: read and write load-staging files
gcloud storage buckets add-iam-policy-binding "${STAGING_BUCKET}" \
--member="serviceAccount:${SA_EMAIL}" \
--role="roles/storage.objectAdmin"
# Download the JSON key — paste its contents into the form field
gcloud iam service-accounts keys create platinur-svc-key.json \
--iam-account="${SA_EMAIL}" \
--project="${PROJECT_ID}"
Keep platinur-svc-key.json secure; delete it locally after pasting into the form. If you prefer dataset-scoped grants instead of project-level bigquery.dataEditor, create the target datasets first and bind roles/bigquery.dataEditor per dataset. roles/bigquery.jobUser must remain at the project level.
Form field mapping:
- GCP project ID → Project ID
- Contents of
platinur-svc-key.json → Service-account key (JSON)
US / EU / region string → Location
platinur (or chosen name) → Default dataset
gs://my-platinur-staging/... → Staging GCS bucket URL
Databricks
You need: a Databricks workspace, a running SQL warehouse, a Unity Catalog with a dedicated catalog, a personal access token (PAT) or OAuth M2M token, and a dlt staging location. Platinur uses 3-level Unity Catalog addressing (catalog.schema.table) — the legacy hive_metastore is not supported.
| Form field | What it is | How to obtain it |
|---|
| Workspace host | Workspace URL without https://, e.g. dbc-xxxx.cloud.databricks.com | Read — copy the hostname from your browser’s address bar when logged into the workspace |
| SQL warehouse HTTP path | HTTP path of the SQL warehouse Platinur connects to | Read — SQL Warehouses → select warehouse → Connection details tab → HTTP path |
| Access token (PAT) (secret) | Personal access token or OAuth M2M token | Create — workspace → user name (top-right) → User settings → Developer → Access tokens → Generate new token |
| Unity catalog | Name of the Unity Catalog catalog Platinur builds into | Create — see provisioning snippet below (platinur) |
| Default schema | Starting schema within the catalog (default default) | Leave as default; Platinur creates layer schemas automatically |
| Staging Unity Catalog volume | UC volume path dlt writes load files to, e.g. /Volumes/platinur/staging/dlt | Create — CREATE VOLUME inside the catalog; preferred staging method (no extra bucket credentials needed) |
| Staging cloud bucket URL | Cloud bucket (s3://, abfss://, gs://) as an alternative staging location | Create — provision a cloud bucket accessible from the workspace; use only when a UC volume is not available |
At least one staging field (Staging Unity Catalog volume or Staging cloud bucket URL) must be set to run Integrations source loads. The UC volume approach is preferred — the workspace token authorizes it directly with no additional bucket credentials.
Where to find the SQL warehouse HTTP path. In your Databricks workspace, open SQL Warehouses in the left sidebar, click your warehouse, then open the Connection details tab. The HTTP path looks like /sql/1.0/warehouses/abc123def456.
Provisioning snippet (run as a Unity Catalog admin):
-- Create a dedicated catalog for Platinur
CREATE CATALOG IF NOT EXISTS platinur
COMMENT 'Platinur analytics engineering output';
-- Grant the service principal (or the user whose PAT you use) access to the catalog.
-- Replace <principal> with the service principal application ID or user email.
GRANT USE CATALOG ON CATALOG platinur TO `<principal>`;
GRANT CREATE SCHEMA ON CATALOG platinur TO `<principal>`;
GRANT USE SCHEMA ON CATALOG platinur TO `<principal>`;
GRANT CREATE TABLE ON CATALOG platinur TO `<principal>`;
GRANT MODIFY ON CATALOG platinur TO `<principal>`;
-- Create a schema and managed volume for dlt staging (preferred)
CREATE SCHEMA IF NOT EXISTS platinur.staging;
CREATE VOLUME IF NOT EXISTS platinur.staging.dlt
COMMENT 'dlt load-file staging for Platinur Integrations';
GRANT READ VOLUME ON VOLUME platinur.staging.dlt TO `<principal>`;
GRANT WRITE VOLUME ON VOLUME platinur.staging.dlt TO `<principal>`;
-- Grant read access to source catalogs/schemas Platinur should model from.
-- Repeat for each source schema.
-- GRANT USE CATALOG ON CATALOG <source_catalog> TO `<principal>`;
-- GRANT USE SCHEMA ON SCHEMA <source_catalog>.<source_schema> TO `<principal>`;
-- GRANT SELECT ON ALL TABLES IN SCHEMA <source_catalog>.<source_schema> TO `<principal>`;
Generate a PAT in the workspace under your user name (top-right) → User settings → Developer → Access tokens → Generate new token. Copy it immediately — it is shown only once.
Form field mapping:
- Workspace hostname (no
https://) → Workspace host
- HTTP path from Connection details → SQL warehouse HTTP path
- Generated PAT → Access token (PAT)
platinur → Unity catalog
/Volumes/platinur/staging/dlt → Staging Unity Catalog volume
Redshift
You need: a Redshift cluster endpoint, a target database, a dedicated service user (password auth) or an IAM-enabled cluster (IAM auth), and an S3 bucket with access credentials for dlt staging. All sensitive values are stored as secret refs.
| Form field | What it is | How to obtain it |
|---|
| Endpoint host | Cluster endpoint hostname (strip the :port suffix) | Read — Redshift console → Clusters → your cluster → General information → Endpoint |
| Port | Redshift port (default 5439) | Read — shown alongside the endpoint in the console |
| Database | Database name Platinur connects to | Create or Read — use an existing analytics database or create one |
| Auth method | password or iam | Choose based on your cluster’s auth configuration |
| User | Redshift username | Create — see provisioning snippet below (PLATINUR_SVC) |
| Password (secret) | Password for the Redshift user (password auth) | Create — set in CREATE USER |
| Cluster identifier (IAM) | Short cluster name used for IAM token exchange (IAM auth only) | Read — the cluster name without the endpoint hostname suffix, e.g. my-cluster |
| IAM profile (IAM) | Named AWS profile with redshift:GetClusterCredentials permission (IAM auth only) | Read — the named profile from your own AWS IAM configuration; leave blank to use the default credential chain |
| Default schema | Default schema Platinur uses (default public) | Leave as public; Platinur creates layer schemas automatically |
| SSL mode | SSL connection mode (default prefer) | Set to require for strict TLS enforcement |
| Staging S3 bucket URL | s3://bucket/prefix dlt writes load files here before Redshift COPY | Create — provision an S3 bucket in the same region as the cluster; required to run Integrations source loads |
| Staging AWS access key ID (secret) | IAM access key ID for the staging bucket (static-key auth) | Create — IAM → Users → staging IAM user → Security credentials → Create access key |
| Staging AWS secret access key (secret) | IAM secret access key (static-key auth) | Create — shown once when the access key is created |
| Staging IAM role ARN | IAM role the cluster assumes for COPY (role-based staging auth) | Create or Read — IAM → Roles; attach the role to the cluster in the Redshift console |
The Staging S3 bucket URL is required for dlt Integrations loads. Provide either a static key pair (Staging AWS access key ID + Staging AWS secret access key) or an IAM role ARN (Staging IAM role ARN) to authorize COPY access. Do not supply both.
Provisioning snippet (password auth; run as a superuser in the target database):
-- Create the Platinur service user
CREATE USER PLATINUR_SVC
PASSWORD '<choose-a-strong-password>'
CONNECTION LIMIT 10;
-- Allow the user to create schemas in the target database.
-- Platinur manages its own output schemas (stg_staging, stg_dw, stg_marts, etc.).
GRANT CREATE ON DATABASE analytics TO PLATINUR_SVC;
-- Grant read access to source schemas Platinur should model from.
-- Repeat for each schema containing raw source tables.
-- GRANT USAGE ON SCHEMA <source_schema> TO PLATINUR_SVC;
-- GRANT SELECT ON ALL TABLES IN SCHEMA <source_schema> TO PLATINUR_SVC;
-- ALTER DEFAULT PRIVILEGES IN SCHEMA <source_schema>
-- GRANT SELECT ON TABLES TO PLATINUR_SVC;
IAM auth. Set Auth method to iam, enter the short Cluster identifier (the cluster name, not the full endpoint hostname), and optionally an IAM profile name. The IAM principal must have redshift:GetClusterCredentials and redshift:CreateClusterUser on the cluster.
S3 staging with an IAM role. Attach the IAM role to the cluster in the Redshift console (Clusters → your cluster → Properties → IAM roles), then paste the role ARN into Staging IAM role ARN. Leave the static key fields blank.
Form field mapping:
- Cluster endpoint hostname → Endpoint host
analytics (or your db name) → Database
PLATINUR_SVC → User
<choose-a-strong-password> → Password
- S3 bucket URL → Staging S3 bucket URL
- IAM access key → Staging AWS access key ID + Staging AWS secret access key (or role ARN → Staging IAM role ARN)
Output namespaces
Regardless of engine, output namespaces follow the same fixed convention: {stg|prod}_{layer}.
On ClickHouse these are flat databases: stg_staging, stg_dw, stg_marts for staging and prod_staging, prod_dw, prod_marts for production.
On all other engines these are schemas (Snowflake, Redshift), datasets (BigQuery), or schemas within the Unity Catalog (Databricks), created under the bound database, project, or catalog. Platinur creates and manages these namespaces; they must not be modified outside Platinur.
The same convention applies to source data: each configured or externally loaded source lands in its own raw_<source> namespace, with a fallback raw namespace for sources that do not specify one. See External Source Schemas and Source Load Modes.
A throwaway <analytics>_validation sandbox is created and dropped automatically for each validation run — do not depend on it persisting.
Account reset
The account reset is the one supported way to unbind the warehouse engine and start over with a different engine kind. It is an irreversible administrative action.
Endpoint: POST /api/account/reset — owner/admin only.
Required body:
{
"confirm": "RESET",
"drop_warehouse_objects": false
}
confirm must be the literal string "RESET".
drop_warehouse_objects: true instructs Platinur to drop its own env output and validation namespaces (stg_*, prod_*, *_validation) before clearing the binding. Set to false to leave those namespaces in place.
The reset never touches customer raw or source schemas — only Platinur-owned output namespaces are eligible for the optional drop.
After a reset the account is empty again: no warehouse binding, no generated models, no run history. A new engine can then be selected and tested from Configuration.