Skip to content
This repository has been archived by the owner on Oct 9, 2023. It is now read-only.

Commit

Permalink
Merge pull request #160 from snaplet/kz-hotfix-preview-dbs
Browse files Browse the repository at this point in the history 
update image paths on preview-dbs.md
  • Loading branch information
@peterp
peterp authored May 9, 2023
2 parents 7cc133c + 603a136 commit fbb3d6d
Showing 1 changed file with 33 additions and 116 deletions.
149 changes: 33 additions & 116 deletions docs/04-references/preview-databases.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,39 +8,37 @@ This feature is actively under development and is subject to change. We would lo

## Why preview databases?

The typical Snaplet workflow involves restoring snapshots to your local development PostgreSQL database to code against. While working locally with snapshots allows for more flexibility, configurability, and the ability to work offline without network latency or connectivity interruptions, there are situations where being able to preview your snapshot on an instant serverless database (what we call "preview databases") is useful.
The typical Snaplet workflow involves restoring snapshots to your local development PostgreSQL database to code against. While working locally with snapshots allows for more flexibility, configurability, and the ability to work offline without network latency or connectivity interruptions, there are situations where being able to preview your snapshot on an instant serverless database (what we call "preview databases") is useful.

For example, if you're currently in the process of evaluating Snaplet, being able to restore a snapshot to a preview database allows you to view that database without needing to download and install the Snaplet CLI. Preview databases are also easy to share with team members, and allow you to have [isolated preview databases](/guides/netlify-preview-plugin) for preview deployments.
For example, if you're currently in the process of evaluating Snaplet, being able to restore a snapshot to a preview database allows you to view that database without needing to download and install the Snaplet CLI. Preview databases are also easy to share with team members, and allow you to have [isolated preview databases](/guides/netlify-preview-plugin) for preview deployments.

As such, Snaplet supports the creation of instant preview databases from snapshots, which allows users to view, code against, or run pull-request previews against a preview serverless PostgreSQL database.
As such, Snaplet supports the creation of instant preview databases from snapshots, which allows users to view, code against, or run pull-request previews against a preview serverless PostgreSQL database.

These preview databases can be created from within the [Snaplet Cloud](/references/preview-databases#creating-a-preview-database-on-snaplet-cloud) dashboard, or the [Snaplet CLI](/references/preview-databases#creating-a-preview-database-using-snaplet-cli-deprecated).

Each Snaplet Project receives a PostgreSQL server instance where multiple preview databases can be created.
Each Snaplet Project receives a PostgreSQL server instance where multiple preview databases can be created.

## Creating a preview database on Snaplet Cloud

To create a preview database from within Snaplet Cloud, you'll need to have captured a snapshot from your source database - refer to the [Getting Started](/getting-started/start-here/) guide if you need help. From the Snaplet dashboard, click on your snapshot, and then select the 'Previews' tab. From here, simply click the 'Create new preview database' button.
To create a preview database from within Snaplet Cloud, you'll need to have captured a snapshot from your source database - refer to the [Getting Started](/getting-started/start-here/) guide if you need help. From the Snaplet dashboard, click on your snapshot, and then select the 'Previews' tab. From here, simply click the 'Create new preview database' button.

<div style={{textAlign: 'center'}}>
<img align="center" width="480" src="/static/screenshots/preview-db/preview-database-01.png" alt="Create a new preview database" />
<img align="center" width="480" src="/screenshots/preview-db/preview-database-01.png" alt="Create a new preview database" />
</div>

The first preview database may take a moment to create, depending on the size of your snapshot. Once done, you'll be able to copy the connection string for the database to import into your preferred database client.
The first preview database may take a moment to create, depending on the size of your snapshot. Once done, you'll be able to copy the connection string for the database to import into your preferred database client.

<div style={{textAlign: 'center'}}>
<img align="center" width="480" src="/static/screenshots/preview-db/preview-database-02.png" alt="Copy connection string" />
<img align="center" width="480" src="/screenshots/preview-db/preview-database-02.png" alt="Copy connection string" />
</div>


:::note Info

Currently, preview databases created from within the Snaplet CLI use a legacy database provider that's different from the provider used for preview databases created from within the Snaplet Cloud application. Our intention is to deprecate the current provider for Snaplet CLI databases, transition to the new provider, and harmonize preview databases on a single provider. **For now, we'd recommend using Snaplet Cloud to create preview databases**.
Currently, preview databases created from within the Snaplet CLI use a legacy database provider that's different from the provider used for preview databases created from within the Snaplet Cloud application. Our intention is to deprecate the current provider for Snaplet CLI databases, transition to the new provider, and harmonize preview databases on a single provider. **For now, we'd recommend using Snaplet Cloud to create preview databases**.

:::


## Creating a preview database using Snaplet CLI (deprecated)
## Creating a preview database using Snaplet CLI

:::note Info

Expand All @@ -52,138 +50,57 @@ The database server is hosted on a [Fly Machine](https://fly.io/docs/reference/m

```bash
# highlight-next-line
$ snaplet database --help
$ snaplet preview-database --help

snaplet database [action]
snaplet preview-database [action]

manage preview databases

Commands:
snaplet database cache [snapshot] cache a snapshot into the preview database server [aliases: ca]
snaplet database create [database-name] [snapshot] create a preview database from a snapshot [aliases: c]
snaplet database destroy destroy the database server [aliases: ds]
snaplet database drop [database-name] drop a preview database [aliases: delete, d]
snaplet database list list preview databases [aliases: ls]
snaplet database setup create a preview database server [aliases: s]
snaplet database url [database-name] show a preview database url [aliases: u]
snaplet preview-database create [snapshot] create a preview database from a snapshot [aliases: c]
snaplet preview-database url [name] get a connection URL for a specified preview database [aliases: u]
snaplet preview-database list [snapshot] shows all preview databases created from a specific snapshot [aliases: ls]
snaplet preview-database drop [name] drops a specified preview database [aliases: d]
```

For the following commands, we will use the convenient alias `db` in place of `database`.

## Creating a database server

The first step is to create a database server in the region of your choice.

Run `snaplet db setup`

## Creating a database
## `create [snapshot]`

To create a database from a snapshot, run `snaplet db create`:
The create subcommand generates a new preview database using a specified snapshot:

```bash
# highlight-next-line
$ snaplet db create preview_db_tutorial
# You will be asked to pick a snapshot if you don't provide one using the --snapshot or --latest option
✔ Snapshot › v1-cassidy-underpass-interface 483 kB 4 days ago
# The snapshot is restored to the preview database
✔ Database preview_db_tutorial created from snapshot v1-cassidy-underpass-interface [12s]
# You can now use your database!
You can connect to your database at: postgresql://postgres:*********@<ipv4>:5432/preview_db_tutorial
```

If you don't want to provide an explicit name for the database, you can use the `--git` option. Your database will be named after your current branch name:
**Examples**

```bash
# highlight-next-line
$ snaplet db create --git --latest
# Assuming that we are on the branch "snappy/feature-meow"
✔ Database snappy_feature_meow created from snapshot v1-cassidy-underpass-interface [11s]
You can connect to your database at: postgresql://postgres:*********@snaplet-<orgId>-<projectId>.fly.dev:5432/snappy_feature_meow
# To create a new preview database from a specific snapshot, run:
snaplet preview-database create preview_db_tutorial
```

The `--git` option is available for database creation, deletion and displaying the database url.
## `url [name]`

## Listing databases
This command retrieves the connection URL for a specified preview database. The name parameter is optional and if not provided, the most recent preview database will be used.

To list all databases, run `snaplet db list`:
**Examples**

```bash
# highlight-next-line
$ snaplet db list
DATABASES
NAME SIZE SNAPSHOT
preview_db_tutorial 14 MB v1-cassidy-underpass-interface
snappy_feature_meow 14 MB v1-cassidy-underpass-interface
# To get the connection URL for a specific preview database, run:
snaplet preview-database url preview_db_tutorial
```

You can see the database size and from which snapshot each database was created.

## Dropping a database
## `list [snapshot]`

To drop a database, run `snaplet db drop`:
The list subcommand shows all preview databases created from a specific snapshot:

```bash
# highlight-next-line
$ snaplet db drop preview_db_tutorial
✔ Dropped database preview_db_tutorial
# To list all preview databases that have been created from a specific snapshot, run:
snaplet preview-database list preview_db_tutorial
```

## Displaying a database url
## `drop [name]`

To display a database url, run `snaplet db url`:
This command drops a specified preview database. The name parameter is required and specifies the name of the preview database to drop.

```bash
# highlight-next-line
$ snaplet db url snappy_feature_meow
postgresql://postgres:*********@snaplet-<orgId>-<projectId>.fly.dev:5432/snappy_feature_meow
snaplet preview-database drop preview_db_tutorial
```

This command is especially helpful in CI/CD or preview environments: `DATABASE_URL=$(snaplet db url --git) yarn prisma migrate deploy`

## Caching a snapshot into the database server

Waiting for a snapshot to be restored can be long, especially if your snapshot is big.
To avoid this problem, you can cache snapshots into the database server for truly preview databases creation!

To cache a snapshot into the database server, run `snaplet db cache`:

```bash
# highlight-next-line
$ snaplet db cache v1-cassidy-underpass-interface
✔ Snapshot v1-cassidy-underpass-interface cached into preview database server [12s]

# highlight-next-line
$ snaplet db create is_it_fast_enough --snapshot v1-cassidy-underpass-interface
✔ Database is_it_fast_enough created from cached snapshot v1-cassidy-underpass-interface [389ms] # Notice the time here!
You can connect to your database at: postgresql://postgres:*********@snaplet-<orgId>-<projectId>.fly.dev:5432/is_it_fast_enough
```

The cached snapshots will appear in the `snaplet db list` command:

```bash
# highlight-next-line
$ snaplet db list
DATABASES
NAME SIZE SNAPSHOT
is_it_fast_enough 14 MB v1-cassidy-underpass-interface

CACHED SNAPSHOTS
NAME SIZE
v1-cassidy-underpass-interface 14 MB
```

## Clearing a cached snapshot from the database server

To clear a cached snapshot, run `snaplet db cache --clear`:

```bash
# highlight-next-line
$ snaplet db cache v1-cassidy-underpass-interface --clear
Snapshot v1-cassidy-underpass-interface removed from the preview database server cache
```

## Destroying a the database server

If you want to restart from scratch, you can run the `snaplet db destroy` command.

It will delete the database server with all its preview databases.

0 comments on commit fbb3d6d

Please sign in to comment.