Deploy TiDB Cluster

Deploy and Host TiDB Cluster on Railway

TiDB is an open-source distributed SQL database designed for scalability, strong consistency, and MySQL compatibility.

This Railway template deploys a minimal TiDB cluster using separate TiDB, PD, and TiKV services connected through Railway Private Networking.

About Hosting

Hosting TiDB Cluster on Railway gives you a simplified distributed SQL environment without manually provisioning multiple virtual machines or managing Kubernetes.

This template deploys:

• TiDB as the SQL processing layer
• PD for cluster metadata and placement management
• TiKV as the persistent transactional storage layer

Only the TiDB service should be accessed by applications.

PD and TiKV remain internal and communicate through Railway Private Networking.

For external database connections, use Railway TCP Proxy on the TiDB service instead of an HTTP public domain.

Why Deploy

Deploying TiDB Cluster on Railway makes it easier to experiment with distributed SQL while keeping infrastructure management relatively simple.

This template is useful when you want to:

• Run a MySQL-compatible distributed SQL database
• Test TiDB architecture with PD and TiKV
• Separate SQL processing from persistent storage
• Build applications using standard MySQL drivers
• Experiment with distributed database behavior
• Use Railway Private Networking for cluster communication
• Persist PD metadata and TiKV data with Railway Volumes
• Access TiDB externally through Railway TCP Proxy
• Develop and test applications before moving to a larger TiDB deployment

This template uses a minimal topology:

1× TiDB
1× PD
1× TiKV

> ⚠️ This topology is intended for development, testing, learning, and lightweight workloads. It is not a High Availability TiDB deployment.

Common Use Cases

• Distributed SQL development
• MySQL-compatible application backends
• TiDB integration testing
• Database migration testing
• Transactional application development
• Distributed database experiments
• Cloud-native application prototypes
• Backend development
• Learning TiDB architecture
• Testing MySQL-compatible frameworks and ORMs

Dependencies for TiDB Cluster

This template deploys three core TiDB components.

TiDB

• Image: pingcap/tidb
• Provides the MySQL-compatible SQL endpoint
• Default SQL port: 4000
• Connects to PD through Railway Private Networking
• Does not require persistent storage

PD

• Image: pingcap/pd
• Manages cluster metadata
• Handles scheduling and placement information
• Default client port: 2379
• Uses a persistent Railway Volume
• Accessible only through Railway Private Networking

TiKV

• Image: pingcap/tikv
• Provides transactional key-value storage
• Default service port: 20160
• Stores database data on a persistent Railway Volume
• Connects to PD through Railway Private Networking

No additional services are required.

This template does not require:

• PostgreSQL
• MySQL
• Redis
• MinIO
• S3-compatible object storage
• Railway Bucket

Architecture

                Application
                     │
                     │ MySQL Protocol
                     ▼
              ┌─────────────┐
              │    TiDB     │
              │    :4000    │
              └──────┬──────┘
                     │
                     │ Railway Private Network
                     ▼
              ┌─────────────┐
              │     PD      │
              │    :2379    │
              │             │
              │  /data/pd   │
              └──────┬──────┘
                     ▲
                     │
              ┌──────┴──────┐
              │    TiKV     │
              │   :20160    │
              │             │
              │ /data/tikv  │
              └─────────────┘

The dependency flow is:

TiDB ─────► PD
TiKV ─────► PD

PD provides cluster coordination and metadata services, while TiKV stores the actual application data.

Storage

Persistent Railway Volumes are used only for stateful components.

Do not delete or replace the PD or TiKV volumes after the cluster contains important data.

Networking

Cluster communication should remain private.

TiDB

• SQL port: 4000
• Accessible internally through Railway Private Networking
• External access should use Railway TCP Proxy

PD

• Client port: 2379
• Peer port: 2380
• Private only
• Do not expose using a public domain

TiKV

• Service port: 20160
• Status port: 20180
• Private only
• Do not expose using a public domain

TiDB and TiKV reference PD through its Railway private hostname.

Example:

PD_HOST="${{pd.RAILWAY_PRIVATE_DOMAIN}}" # Private hostname of the PD service

Connecting to TiDB

TiDB uses the MySQL wire protocol.

It is not an HTTP API.

From Another Railway Service

Applications deployed in the same Railway project can connect using the TiDB private hostname.

Example:

tidb.railway.internal:4000

or through the generated Railway private domain reference.

From Outside Railway

Enable TCP Proxy on the TiDB service.

Then connect using a MySQL-compatible client.

Example:

mysql \
  -h  \
  -P  \
  -u root

Compatible clients include:

• MySQL CLI
• DBeaver
• DataGrip
• TablePlus
• MySQL Workbench
• MySQL-compatible application drivers

Do not use a Railway HTTP public domain for port 4000.

Important Environment Variables

Only the variables that are relevant to the Railway deployment are shown below.

TiDB

PORT="4000" # MySQL-compatible TiDB SQL port
PD_HOST="${{pd.RAILWAY_PRIVATE_DOMAIN}}" # Private hostname of the PD service

PD

PORT="2379" # PD client port used by TiDB and TiKV
RAILWAY_RUN_UID="0" # Allow PD to write to the Railway-mounted volume

TiKV

PORT="20160" # TiKV service port
PD_HOST="${{pd.RAILWAY_PRIVATE_DOMAIN}}" # Private hostname of the PD service
RAILWAY_RUN_UID="0" # Allow TiKV to write to the Railway-mounted volume

Initial Database Security

A fresh TiDB deployment may allow the root account without a password depending on the upstream configuration.

After deployment, secure the database before exposing it to external clients.

Example:

ALTER USER 'root'@'%' IDENTIFIED BY 'your-strong-password';

For applications, use a dedicated user instead of the root account.

Example:

CREATE DATABASE app;

CREATE USER 'app'@'%' IDENTIFIED BY 'your-strong-password';

GRANT ALL PRIVILEGES ON app.* TO 'app'@'%';

Important Notice

> ⚠️ This template is not a High Availability TiDB deployment.

The template runs:

• 1× TiDB
• 1× PD
• 1× TiKV

This topology does not provide node-level redundancy.

If PD or TiKV becomes unavailable, the cluster may become unavailable until the affected service is restored.

Production-grade TiDB environments typically use multiple PD and TiKV instances to provide redundancy, fault tolerance, and quorum-based operation.

Use this template primarily for:

• Development
• Testing
• Learning
• Integration environments
• Lightweight workloads
• Non-critical deployments

TiDB Cluster vs Traditional Databases

Why Railway

Railway simplifies the infrastructure required to run a minimal TiDB cluster.

This template uses:

• Railway Private Networking for TiDB, PD, and TiKV communication
• Railway Volumes for persistent PD and TiKV storage
• Railway reference variables for internal service discovery
• Railway TCP Proxy for external MySQL-compatible connections
• Isolated services for each TiDB component
• Automatic container deployment and restart management

This provides a practical way to deploy and experiment with TiDB without manually provisioning multiple servers or operating a Kubernetes cluster.