How to Configure TimescaleDB Replication User

Published
Length
3 min read

Luis Felipe Dias

All posts

To set up a timescaledb replication user, create a dedicated database role with replication rights. Then update the host access rules to let the standby server log in. Many teams use the main admin role to start streaming data right away. This shortcut gives the replica full control over every table and chunk. If a bad actor steals that key, they can delete your whole database. How a timescaledb replication user works in practice TimescaleDB runs on PostgreSQL and uses the same write-ahead lo

Your coding agents run with your access.

Claude Code reaches prod with a developer's credentials, and approval prompts get clicked through. hoop.dev checks every query, masks sensitive data, and holds risky changes for a human.

To set up a timescaledb replication user, create a dedicated database role with replication rights. Then update the host access rules to let the standby server log in. Many teams use the main admin role to start streaming data right away. This shortcut gives the replica full control over every table and chunk. If a bad actor steals that key, they can delete your whole database.

How a timescaledb replication user works in practice

TimescaleDB runs on PostgreSQL and uses the same write-ahead log to copy data. The primary server writes every new row and chunk change to this log. A standby server connects using the timescaledb replication user and reads that stream. This role does not need normal table read rights for physical streaming. It only needs the database replication attribute and a strong password or certificate.

Next, the database admin updates the host access list on the primary node. You add a rule that ties the role to the standby IP address. This rule ensures the role can only start a log stream from known hosts. For logical streaming, the setup changes a bit. The role also needs read rights on the parent tables and internal chunks. Since TimescaleDB makes new chunks over time, admins must grant default read rights too.

Why you should separate admin and replication roles

Using the main superuser for streaming is a common mistake during fast builds. It works on day one because the superuser skips all permission checks. Yet this setup creates a huge risk for your production data. The standby server stores the login key in plain text on its disk. Anyone who reads that file on the replica gains admin access to the primary.

A scoped role stops this lateral move before it starts. When you limit the role to streaming, it cannot drop tables or change schemas. You can also rotate the password for the replica without breaking your main apps. Also, database logs become much easier for your security team to read. You can see right away which sessions come from replicas and which come from engineers.

User Provisioning (SCIM) + End-to-End Encryption: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

What native database roles solve and what they miss

Native roles do a great job of locking down server-to-server data streams. They restrict what a login can do at the moment the session starts. Once you scope the standby role, your physical log stream stays tight and clean. The database engine handles these checks fast and without extra tools.

Still, a static role only checks who logs in at the door. It cannot inspect what individual queries do once a session is open. When engineers or Logical ETL tools log in, they need broad read rights. A standard database role cannot rewrite sensitive fields like emails or phone numbers in results. It also cannot ask a team lead to approve a single risky command in flight. Teams still need a way to govern live human and app sessions per query.

Add runtime guardrails and masking beside your databases and APIs

Login rules, role grants, and CI checks govern who connects to your stack. Yet any allowed script, engineer, or AI agent still runs commands with the full scope of its role. For workloads on Postgres, MySQL, SQL Server, MongoDB, ClickHouse, Kubernetes, SSH, or internal HTTP services, hoop.dev sits inline in the protocol beside the service as an open-source proxy, a sidecar for your database or API. On every production query an agent or human runs, hoop.dev decides whether to pass, mask, block, or escalate it for review.

Before a query runs, hoop.dev guardrails check the statement against your rules, an AI Analyzer you configure can score intent or hold risky calls for human approval, and hoop.dev data masking rewrites sensitive fields in responses in memory. Explore the MIT-licensed project on GitHub.

Frequently asked questions

Does a physical replica role need read access to hypertables?

No, physical streaming works at the disk block level using the write-ahead log. The role only needs the replication permission and login rights, not table read grants.

How does logical replication change the role setup in TimescaleDB?

Logical streaming reads rows from tables instead of raw disk blocks. The role needs read rights on the hypertable, existing chunks, and future chunks.

How can I secure the login secret for the standby server?

Use client TLS certificates instead of passwords whenever your setup allows it. Also limit the host rule so only the exact standby IP address can log in.

The query runs. The emails stay hidden.