---
title: Preview Environments
url: "/docs/apps/preview-environments/"
canonical_url: https://docs.blossom88.com/docs/apps/preview-environments/
markdown_url: https://docs.blossom88.com/docs/apps/preview-environments.md
summary: Full copies of an Environment, database included, for every branch or pull
  request
---

# Preview Environments

A Preview is a full copy of an Environment on another branch, with its own
URL and its own database. Use it to try a change for real before it reaches
staging or production. For a quick start, see
[Preview Every Pull Request](/learn/previews/).

## Create Previews

| Create | How |
|---|---|
| By hand | **New Preview** on the Previews page |
| For every pull request | **Pull requests into** in Preview Settings |
| For matching branches | **Branches matching** a pattern such as `preview/*` |

Select one or both triggers in Preview Settings, then save to enable automatic
Previews.

From the CLI, create one by hand with:

    blossom environment:preview:create --id ENVIRONMENT_ID --branch checkout-redesign -f

Automatic Previews need the repository connected through GitHub, GitLab or
Bitbucket. Each push to a branch deploys its Preview. A closed or merged pull
request, or a deleted branch, deletes it. On GitHub, Blossom comments on the
pull request with the Preview's URL and who can open it. Pull requests from
forks never get a Preview, so outside code never runs with your variables.

## What A Preview Shares

Each deploy takes the Environment's current Services, build settings, deploy
hooks and variables, so a change there reaches every Preview on its next
deploy. A Preview keeps its own:

- **URL:** a generated one; custom domains stay with the Environment
- **Database:** its own PostgreSQL database when the Environment links one
- **Variables:** overrides for Previews only, such as a sandbox payment key
- **Access:** Account members by default, with its own
  [share links](/docs/apps/environment-access/#previews)

Override a variable for one Preview:

    blossom env_var:push --environment PREVIEW_ID --file .env.preview

## Databases

When the Environment links PostgreSQL, each Preview gets its own database,
linked under the same variable, usually `DATABASE_URL`. It starts empty, and
two settings fill it:

- **Setup command:** runs once before a new Preview's first release, such as
  `bin/rails db:prepare db:seed`.
- **Preview data:** a sample database every new Preview starts from. Upload a
  PostgreSQL custom archive of up to 250 MB:

      pg_dump --format=custom --no-owner --no-privileges --file sample.dump SAMPLE_DATABASE
      blossom environment:preview:data:upload --environment ENVIRONMENT_ID --file sample.dump

Use sample data, not a copy of production, since share links can open a
Preview to people outside your Account.

## Preview Settings

**Previews → Settings** controls every Preview of the Environment:

- **Container size:** Micro by default, or Small, Medium, Large, or each
  Service's own size. Small containers keep Previews light on resources.
- **Delete after:** 1, 3, 7 (the default), 14 or 30 days without a deploy,
  so a forgotten Preview frees its resources
- **Maximum Previews:** 5, 10 (the default), 20 or 50
- **Access:** Account members, or the same as the Environment

From the CLI, `environment:preview:settings:init` writes the same settings
to edit, and `environment:preview:settings:update` saves them.

## Delete Previews

Previews delete themselves when their pull request closes or they go
unused. To delete them yourself:

    blossom environment:delete --id PREVIEW_ID --yes -f
    blossom environment:preview:delete_all --environment ENVIRONMENT_ID --yes

## Requirements

- Previews work for Environments that deploy from a Git repository, without
  Persistent Services.
- Preview databases are PostgreSQL.