--- title: Fork services | Tiger Data Docs description: Fork a Tiger Cloud service to create isolated branches for testing and development --- Modern development is highly iterative. Developers and AI agents need safe spaces to test changes before deploying them to production. Forkable services make this natural and easy. Spin up a branch, run your test, throw it away, or merge it back. A fork is an exact copy of a service at a specific point in time, with its own independent data and configuration, including: - The database data and schema - Configuration - An admin `tsdbadmin` user with a new password Forks are fully independent. Changes to the fork don’t affect the parent service. You can query them, run migrations, add indexes, or test new features against the fork without affecting the original service. Forks are a powerful way to share production-scale data safely. Testing, BI and data science teams often need access to real datasets to build models or generate insights. With forkable services, you easily create fast, zero-copy branches of a production service that are isolated from production, but contain all the data needed for analysis. Rapid fork creation dramatically reduces friction getting insights from live data. ## Understand service forks You can use service forks for disaster recovery, CI/CD automation, and testing and development. For example, you can automatically test a major PostgreSQL upgrade on a fork before applying it to your production service. Tiger Cloud offers the following fork strategies: - `now`: create a fresh fork of your database at the current time. Use when: - You need the absolute latest data - Recent changes must be included in the fork - `last-snapshot`: fork from the most recent [automatic backup or snapshot](/docs/deploy/tiger-cloud/tiger-cloud-aws/high-availability/backup-restore/index.md). Use when: - You want the fastest possible fork creation - Slightly behind current data is acceptable - `timestamp`: fork from a specific point in time within your [retention period](/docs/deploy/tiger-cloud/tiger-cloud-aws/pricing-and-account-management#features-included-in-each-pricing-plan/index.md). Use when: - Disaster recovery from a known-good state - Investigating issues that occurred at a specific time - Testing “what-if” scenarios from historical data The retention period for point-in-time recovery and forking depends on your [pricing plan](/docs/deploy/tiger-cloud/tiger-cloud-aws/pricing-and-account-management#features-included-in-each-pricing-plan/index.md). ### Fork creation speed Fork creation speed depends on your type of service you want to create: - Free: \~30-90 seconds. Uses a Copy-on-Write storage architecture with zero-copy between a fork and the parent. - Paid: varies with the size of your service, typically 5-20+ minutes. Uses traditional storage architecture with backup restore + WAL replay. ### Billing You can fork a free service to a free or a paid service. However, you cannot fork a paid service to a free service. Billing on storage works in the following way: - High-performance storage: - Copy-on-Write: you are only billed for storage for the chunks that diverge from the parent service. - Traditional: you are billed for storage for the whole service. - Object storage tier: - [Tiered data](/docs/build/data-management/storage/manage-storage/index.md) is shared across forks using copy-on-write and traditional storage: - Chunks in tiered storage are only billed once, regardless of the number of forks - Only new or modified chunks in a fork incur additional costs For details, see [Replicas and forks with tiered data](/docs/build/data-management/storage/tiered-data-replicas-forks/index.md). ## Prerequisites To follow the steps on this page: - Create a target [Tiger Cloud service](/docs/get-started/quickstart/create-service/index.md) with the Real-time analytics capability. You need [your connection details](/docs/integrate/find-connection-details/index.md). This procedure also works for [self-hosted TimescaleDB](/docs/get-started/choose-your-path/install-timescaledb/index.md). ## Manage forks using Tiger CLI To manage development forks: 1. **Install Tiger CLI** Use the terminal to install the CLI: - [Debian](#tab-panel-535) - [Ubuntu](#tab-panel-536) - [Red Hat](#tab-panel-537) - [Fedora](#tab-panel-538) - [MacOS](#tab-panel-539) - [Windows PowerShell](#tab-panel-540) - [x-platform](#tab-panel-541) Terminal window ``` curl -s https://packagecloud.io/install/repositories/timescale/tiger-cli/script.deb.sh | sudo os=any dist=any bash sudo apt-get install tiger-cli ``` Terminal window ``` curl -s https://packagecloud.io/install/repositories/timescale/tiger-cli/script.deb.sh | sudo os=any dist=any bash sudo apt-get install tiger-cli ``` Terminal window ``` curl -s https://packagecloud.io/install/repositories/timescale/tiger-cli/script.rpm.sh | sudo os=rpm_any dist=rpm_any bash sudo yum install tiger-cli ``` Terminal window ``` curl -s https://packagecloud.io/install/repositories/timescale/tiger-cli/script.rpm.sh | sudo os=rpm_any dist=rpm_any bash sudo yum install tiger-cli ``` Terminal window ``` brew install --cask timescale/tap/tiger-cli ``` Terminal window ``` irm https://cli.tigerdata.com/install.ps1 | iex ``` Terminal window ``` curl -fsSL https://cli.tigerdata.com | sh ``` 2. **Set up API credentials** 1. Log Tiger CLI into your Tiger Cloud account: ``` tiger auth login ``` Tiger CLI opens Console in your browser. Log in, then click `Authorize`. You can have a maximum of 10 active client credentials. If you get an error, open [credentials](https://console.cloud.tigerdata.com/dashboard/settings) and delete an unused credential. 2. Select a Tiger Cloud project: ``` Auth URL is: https://console.cloud.tigerdata.com/oauth/authorize?client_id=lotsOfURLstuff Opening browser for authentication... Select a project: > 1. Tiger Project (tgrproject) 2. YourCompany (Company wide project) (cpnproject) 3. YourCompany Department (dptproject) Use ↑/↓ arrows or number keys to navigate, enter to select, q to quit ``` If only one project is associated with your account, this step is not shown. Where possible, Tiger CLI stores your authentication information in the system keychain/credential manager. If that fails, the credentials are stored in `~/.config/tiger/credentials` with restricted file permissions (600). By default, Tiger CLI stores your configuration in `~/.config/tiger/config.yaml`. 3. **Test your authenticated connection to Tiger Cloud by listing services** Terminal window ``` tiger service list ``` This call returns something like: - No services: ``` 🏜️ No services found! Your project is looking a bit empty. 🚀 Ready to get started? Create your first service with: tiger service create ``` - One or more services: ``` ┌────────────┬─────────────────────┬────────┬─────────────┬──────────────┬──────────────────┐ │ SERVICE ID │ NAME │ STATUS │ TYPE │ REGION │ CREATED │ ├────────────┼─────────────────────┼────────┼─────────────┼──────────────┼──────────────────┤ │ tgrservice │ tiger-agent-service │ READY │ TIMESCALEDB │ eu-central-1 │ 2025-09-25 16:09 │ └────────────┴─────────────────────┴────────┴─────────────┴──────────────┴──────────────────┘ ``` 4. **Fork the service** Terminal window ``` tiger service fork tgrservice --now --no-wait --name bob ``` You must specify exactly one timing option: `--now` (fork at current state), `--last-snapshot` (fork at last snapshot, faster), or `--to-timestamp` (fork at specific point in time). By default a fork matches the resources of the parent Tiger Cloud service. For paid plans, specify `--cpu` and/or `--memory` for dedicated resources. You see something like: ``` 🍴 Forking service 'tgrservice' to create 'bob' at current state... ✅ Fork request accepted! 📋 New Service ID: 🔐 Password saved to system keyring for automatic authentication 🎯 Set service '' as default service. ⏳ Service is being forked. Use 'tiger service list' to check status. ┌───────────────────┬──────────────────────────────────────────────────────────────────────────────────────────────────┐ │ PROPERTY │ VALUE │ ├───────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────┤ │ Service ID │ │ │ Name │ bob │ │ Status │ │ │ Type │ TIMESCALEDB │ │ Region │ eu-central-1 │ │ CPU │ 0.5 cores (500m) │ │ Memory │ 2 GB │ │ Direct Endpoint │ ..tsdb.cloud.timescale.com: │ │ Created │ 2025-10-08 13:58:07 UTC │ │ Connection String │ postgresql://tsdbadmin@..tsdb.cloud.timescale.com:/tsdb?sslmode=require │ └───────────────────┴──────────────────────────────────────────────────────────────────────────────────────────────────┘ ``` 5. **When you are done, delete your forked service** 1. Use the CLI to request service delete: ``` tiger service delete ``` 2. Validate the service delete: ``` Are you sure you want to delete service ‘’? This operation cannot be undone. Type the service ID ‘’ to confirm: ``` You see something like: ``` 🗑️ Delete request accepted for service ‘’. ✅ Service ‘’ has been successfully deleted. ``` ## Manage forks using Console To manage development forks: 1. **In Tiger Console, ensure the service has a status of `Running` or `Paused`** 2. **Navigate to `Operations` > `Service Management` and click `Fork service`** 3. **Configure the fork, then click `Fork service`** A fork of the service is created. The forked service shows in `Services` with a label specifying which service it has been forked from. ![See the forked service](/docs/_astro/tsc-forked-service.Dpf11G2D_ZVpdFV.webp) 4. **Update the connection strings in your app to use the fork** ## Integrate service forks in your CI/CD pipeline To fork your Tiger Cloud service using GitHub actions: 1. **Store your Tiger Cloud API key as a GitHub Actions secret** 1. In [Tiger Console](https://console.cloud.tigerdata.com/dashboard/settings), click `Create credentials`. 2. Save the `Public key` and `Secret key` locally, then click `Done`. 3. In your GitHub repository, click `Settings`, open `Secrets and variables`, then click `Actions`. 4. Click `New repository secret`, then set `Name` to `TIGERDATA_API_KEY`. 5. Set `Secret` to your Tiger Cloud API key in the following format `:`, then click `Add secret`. 2. **Add the GitHub Actions Marketplace to your workflow YAML files** For example, the following workflow forks a service when a pull request is opened, running tests against the fork, then automatically cleans up. ``` name: Test on a service fork on: pull_request jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Fork Database id: fork uses: timescale/fork-service@v1 with: project_id: ${{ secrets.TIGERDATA_PROJECT_ID }} service_id: ${{ secrets.TIGERDATA_SERVICE_ID }} api_key: ${{ secrets.TIGERDATA_API_KEY }} fork_strategy: last-snapshot cleanup: true name: pr-${{ github.event.pull_request.number }} - name: Run Integration Tests env: DATABASE_URL: postgresql://tsdbadmin:${{ steps.fork.outputs.initial_password }}@${{ steps.fork.outputs.host }}:${{ steps.fork.outputs.port }}/tsdb?sslmode=require run: | npm install npm test - name: Run Migrations env: DATABASE_URL: postgresql://tsdbadmin:${{ steps.fork.outputs.initial_password }}@${{ steps.fork.outputs.host }}:${{ steps.fork.outputs.port }}/tsdb?sslmode=require run: npm run migrate ``` For the full list of inputs, outputs, and configuration options, see the [Tiger Data - Fork Service](https://github.com/marketplace/actions/tiger-data-fork-service) in GitHub marketplace.