ClickHouse

ClickHouse is a column-oriented SQL database for analytics, event data and high-volume reporting. On Moltern, it runs as a private service for applications, services and coding agents in the same workspace environment. It is not exposed as a public website.

What Moltern Provides​

Before You Deploy​

• Choose the environment that should own the data. Development, staging and production databases should be separate when their data or lifecycle differs.
• Review the deployment impact and workspace storage allowance.
• Identify the server-side application, development service or coding agent that needs access. Browser JavaScript should not receive database credentials.
• Plan exports and recovery separately. Runtime persistence is not a backup.

Deploy ClickHouse​

1. Open Services and search for ClickHouse.
2. Select Deploy and choose the target environment.
3. Give the service a recognizable name.
4. Review CPU, memory and storage in the deployment preview.
5. Confirm the deployment and wait for Running.

Expected result: the service becomes Running and shows private connection details in Settings. The absence of an Open public URL is expected for a database.

Connect An Application, Service Or Agent​

Prefer Moltern's private connection controls:

1. Open the consuming workload.
2. Go to Private service connections or the equivalent resource-access settings.
3. Select the ClickHouse service and apply the change.
4. Wait for the workload update, then open a new process or terminal session.
5. Use the scoped variables shown for that connection.

For a client that needs individual fields, open ClickHouse Settings > Connection details. Complete account confirmation when requested and enter the workspace connection-details password. Moltern then reveals the private host, port, database, username and managed password.

Do not use localhost, a public Moltern URL or values copied from another environment. Keep revealed credentials out of source control, screenshots, frontend bundles and terminal history.

Verify The Database​

Use the endpoint and credentials displayed by your own workspace. With a trusted client that supports ClickHouse HTTP, create a disposable MergeTree table:

CREATE TABLE deployment_events (
  id String,
  status LowCardinality(String),
  created_at DateTime DEFAULT now()
)
ENGINE = MergeTree
ORDER BY (created_at, id);

Insert and read a test row:

INSERT INTO deployment_events (id, status)
VALUES ('validation-1', 'created');

SELECT id, status
FROM deployment_events
WHERE id = 'validation-1';

Then verify a real mutation:

ALTER TABLE deployment_events
UPDATE status = 'verified'
WHERE id = 'validation-1'
SETTINGS mutations_sync = 2;

SELECT id, status
FROM deployment_events
WHERE id = 'validation-1';

Expected result: the final query returns validation-1 with verified. This is stronger than checking that the process starts: it exercises the filesystem operations required by ClickHouse MergeTree mutations.

Check Persistence After Restart​

Use a disposable database or a planned maintenance window:

1. Complete the insert and mutation above.
2. Restart the ClickHouse service from Moltern.
3. Wait for the service to return to Running.
4. Run only the final SELECT; do not insert the row again.
5. Confirm the original row still reports verified.

Moltern's release gate performs this write, mutation, restart and read sequence. It also verifies that the service uses its own scoped workspace path and does not create a separate storage volume for each ClickHouse installation.

Capacity, Logs And Usage​

ClickHouse performance depends on CPU, memory, query shape and data layout as well as stored bytes. Review Capacity before changing resources, and test representative queries before treating a size as production-ready.

Capacity changes can restart a single-instance service. Plan for a short interruption and verify clients reconnect. Increasing replicas does not by itself create a ClickHouse cluster or replicated tables.

Use Live logs for startup, permission, mutation and memory errors. Review storage in Billing after the next measurement cycle. Small datasets may round to zero GiB; an unknown or delayed measurement is not proof that the database contains no data.

Backups And Recovery​

This guide does not claim an automatic ClickHouse backup or one-click restore workflow. Persistent storage protects normal restarts, but it does not protect against accidental deletion, bad mutations or workspace loss.

For important data, define a ClickHouse-compatible backup/export procedure, store the copy outside the affected service, and test restoration before relying on it. Follow the official backup guidance for your ClickHouse version.

Troubleshooting​

The service is Running but my client cannot connect: verify the client is in the intended environment, the private connection is applied, and the client is using the exact host and port shown by Moltern.

Authentication fails: reveal the current connection details again. Do not reuse credentials from a deleted or replaced service.

A mutation fails with a filesystem or hardlink error: do not move the data directory to a generic file share or create an unmanaged replacement disk. Collect the sanitized query error and deployment time, then contact support.

The client variable is missing: wait for the attachment update to finish and start a new process or terminal. Existing processes keep their old environment.

Storage still appears after deletion: wait for cleanup to finish and for the next usage measurement. Do not repeatedly create replacements while deletion is still in progress.

Delete ClickHouse Safely​

1. Stop new writes and identify every attached application, service and agent.
2. Export data that must be retained and verify the export can be read.
3. Remove or redirect private connections.
4. Delete ClickHouse through Moltern and confirm the stored-data choice.
5. Wait for cleanup and review the next storage measurement.

Deleting the consuming application does not automatically mean a separately created ClickHouse service should be deleted. An auto-provisioned dependency, however, follows its parent service's confirmed deletion flow.

Frequently Asked Questions​

Why Is There No Public ClickHouse URL?​

ClickHouse is a database protocol/API service. Moltern keeps its connection on the private workspace network so only explicitly connected workloads should use it.

Can A Coding Agent Use ClickHouse?​

Yes, when you explicitly grant that ClickHouse service to the agent. The agent receives scoped connection context; it should not receive unrelated workspace credentials.

Does Running Mean My Database Is Fully Tested?​

No. Running proves the workload became healthy. Validate authentication, a real write, a MergeTree mutation and read-after-restart for your own schema and expected workload.

Official Resources​

• ClickHouse documentation
• ClickHouse SQL reference
• ClickHouse backup and restore guidance
• ClickHouse source code