> For the complete documentation index, see [llms.txt](https://jadelab.gitbook.io/jadegit/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://jadelab.gitbook.io/jadegit/0.18.0/admin/database-images.md).

# Database Images

To speed up environment provisioning while ensuring consistency, teams may choose to maintain a catalog of prebuilt database images.

Key objectives that may motivate their use include:

* Using ephemeral test environments during an automated testing pipeline.
* Reducing the time to set up a local developer workspace.

{% hint style="success" icon="lightbulb" %}
Using the standard Jade platform folder structure, with `bin` and `system` folders, is recommended for both images and snapshots. This simplifies working with them, regardless of how a database was obtained.
{% endhint %}

## Types

The image type conveys its preparation and intended use. Additional types may be prepared beyond those described here — for example, images seeded with artificial test data.

### Empty

An `empty` image is a code-only snapshot of a database. It can be used as the basis for creating other images, or running automated tests which are not data dependent.

These can be created from scratch by loading schemas into a fresh database, which can be achieved using a scripted deployment built by JadeGit from the associated code repository, which will also initialize the registry with the version details.

For large systems, a more efficient approach is to copy the binaries and system data files (`_*.dat`) from an offline or quiesced backup of production, or equivalent, and then use `jdbutilb` to update the database state to reflect that other data files have been implicitly removed. An advantage of this approach is that it preserves any metamodel issues, which may be detected using a meta certify.

#### Fresh Database

The `fresh` database is a special case where its empty image is created from scratch using platform components, combined with any others required as part of a common baseline. It can be used to upgrade empty images for existing databases to a newer platform version, and to create a development image that can be used to set up a workspace for greenfield development.

### Development

The `dev` image is ready-to-use for development, retrieved as needed to set up a local workspace on a developer workstation.

These are created from the empty image by adding the JadeGit binaries and running the install command.

When the registry is used, the fetch command can be used to populate repositories automatically initialized during install using the origin and current commit information stored in the registry.

When the registry isn't used, the clone command can be used to either initialize and populate repositories in an empty image, with the current commit supplied that matches the version of the schemas already in the empty image. Alternatively, a repository can be cloned into a `fresh` image, during which schemas will be built and loaded based on the default branch.

## Storage

The image catalog can be located anywhere common to its consumers. Using cloud hosted blob storage is recommended, but a traditional filesystem can also be used instead.

Images are published within the catalog using the structure:

```
<platform>/<type>/<database>
```

Where `platform` identifies the Jade version and character set (e.g. `22.0.05-ansi`, `25.0.01-ansi`), `type` is the image type (e.g. `dev`, `empty`), and `database` is a canonical name identifying which database the image represents, independent of how it may be named in any particular environment (e.g. `demo`, `finance`, `inventory`).

For example:

```
22.0.05-ansi/
  dev/
    demo/
      bin/
      system/
    finance/
      ...
    fresh/
      ...
    inventory/
      ...
  empty/
    ...

25.0.01-ansi/
  ...
```

This structure makes it straightforward to retrieve a specific image, all images for the same platform and type (useful for development workspaces), or remove all images for a platform when it is no longer used.