--- title: Fork services | Tiger Data Docs description: Fork a service to create isolated database 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](../high-availability/backup-restore). Because Tiger Cloud takes automatic backups daily, this is usually within the previous 24 hours of your service. To see when the latest backup was taken, check [`Backup history`](../high-availability/backup-restore#automatic-backups) in Tiger Console. Use when: - You want the fastest possible fork creation - Up to 24 hours behind current data is acceptable - `timestamp`: fork from a specific point in time, up to 14 days before, depending on your [pricing plan](../pricing-and-account-management#features-included-in-each-pricing-plan). Use when: - Disaster recovery from a known-good state - Investigating issues that occurred at a specific time - Testing “what-if” scenarios from historical data ### Fork creation speed Fork creation speed depends on the type of service you want to create: - Free services: \~30-90 seconds. Use a Copy-on-Write storage architecture with zero-copy between a fork and the parent. - Standard services: varies with the size of your service, typically 5-20+ minutes. Use traditional storage architecture with backup restore + WAL replay. ### Billing You can fork a free service to a free or a standard service. However, you cannot fork a standard 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](/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](/build/data-management/storage/tiered-data-replicas-forks/index.md). ## Prerequisites To follow the steps on this page: - Create a target [Tiger Cloud service](/get-started/quickstart/create-service/index.md) with the Real-time analytics capability. You need [your connection details](/integrate/find-connection-details/index.md). This procedure also works for [self-hosted TimescaleDB](/get-started/choose-your-path/install-timescaledb/index.md). ## Manage forks You cannot fork a service while it is being provisioned or otherwise transitioning state. Wait for the service to reach `Running` or `Paused` before you start forking. - [Tiger CLI](#tab-panel-456) - [Tiger Console](#tab-panel-457) To manage development forks: 1. **Install Tiger CLI** Use the terminal to install the CLI: - [Debian](#tab-panel-449) - [Ubuntu](#tab-panel-450) - [Red Hat](#tab-panel-451) - [Fedora](#tab-panel-452) - [MacOS](#tab-panel-453) - [Windows PowerShell](#tab-panel-454) - [x-platform](#tab-panel-455) 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: Terminal window ``` 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 standard services, 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: Terminal window ``` 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. ``` Tiger Console lets you create development forks and point-in-time recovery (PITR) forks. ### Development forks Development forks use the [`now`](#understand-service-forks) strategy. 1. **In Tiger Console, navigate to `Operations` > `Service Management` and click `Fork service`** ![Fork a Tiger Cloud service](/_astro/create-fork-tiger-console.BhBMTQ17_ZJeJko.webp) 2. **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. 3. **Update the connection strings in your app to use the fork** ### PITR forks PITR forks use the [`timestamp`](#understand-service-forks) strategy. To recover from a destructive or unwanted action, create a fork at a specific point in time. To avoid paying compute for both the recovery fork and the original service, pause the original. 1. **Navigate to `Operations` > `Service management` and click `Create recovery fork`** ![Creating a recovery fork in Tiger Console](/_astro/create-recovery-fork-tiger-console.B_ta8j9w_ZKzU3E.webp) 2. **Select the recovery point, ensuring the correct time zone (UTC offset)** 3. **Select the region** If you had [cross-region backup](../high-availability/backup-restore#enable-cross-region-backup) enabled for your service, select the region in which to create the fork. 4. **Configure the fork to match the original service** Best practice is to match the same configuration you had at the point you want to recover to. You can also add an HA replica, tag the fork, or add a connection pooler. 5. **Confirm by clicking `Create recovery fork`** 6. **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.