Skip to content

Commit

Permalink
docs: update concepts
Browse files Browse the repository at this point in the history
  • Loading branch information
tianzhou committed Jan 27, 2025
1 parent d83edc9 commit c786875
Show file tree
Hide file tree
Showing 2 changed files with 32 additions and 8 deletions.
28 changes: 28 additions & 0 deletions content/docs/change-database/change-workflow.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,34 @@ For a typical change workflow, a developer first submits the SQL statement for D

There are 2 typical workflows employed by the team to deal with database schema changes (DDL) and data changes (DML). [UI workflow](#ui-workflow) and [GitOps workflow (GitOps)](#gitops-workflow).

## Core Concepts

### Release

<HintBlock type="info">

Release is only used in [Custom GitOps workflow](/docs/vcs-integration/custom/overview/).

</HintBlock>

A `release` is a deployable unit that encapsulates a set of SQL statements. You can think of a `release` as a collection of SQL statements layered on top of a scratch Docker image.

### Rollout

To roll out the changes, Bytebase creates a multi-stage rollout pipeline from you project deployment config setting. The changes are pushed to databases stage by stage.

### Issue

`Issue` adds the collaboration such as approval, comment, and notification to the database change process. An issue is often created via the UI workflow. On the other hand, an issue may not be created via the GitOps workflow since the GitOps workflow may only need the [rollout](/docs/change-database/change-workflow/#rollout) without further human intervention.

### Revision

`Revision` records the versioned changes applied to a database. You can get a database from version A to version B by replaying the revisions between A and B. When applying a [release](/docs/change-database/change-workflow/#release) to a database, the changes with a version present in the revision are skipped so that the same changes are not applied twice.

### Changelog

`Changelog` records all changes applied to a database, whether they are versioned or not, successfully applied or not. This includes change database [issues](/docs/change-database/change-workflow/#issue) created on Bytebase UI or [rollout](/docs/change-database/change-workflow/#rollout) via Bytebase APIs, but NOT changes from Bytebase SQL Editor or other external database tools. Changelog offers you insights into the database schema evolution.

## UI workflow

Classic SQL Review workflow where the developer submits a SQL review ticket directly from Bytebase and waits for the assigned DBA or peer developer to review. Bytebase applies the SQL change after review approved.
Expand Down
12 changes: 4 additions & 8 deletions content/docs/concepts/data-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,16 +67,12 @@ A list of databases usually having the same schema structure. Examples like per-

Most of the time, `Developers` work with the `Project`.

## Issue

`Issue` drives the database change workflow such as `Database Creation`, `DDL` and `DML`. It's similar to the issue concept in other issue management tools.

In Bytebase, `Issue` is optimized for **database domain**. An `Issue` always belongs to a `Project`. A single `Issue` is only dealing with a particular `Database Instance` (e.g. creating a database on a database instance). Except for creating database issue, most other issues are also associated with an existing `Database` (e.g. altering a table on a database).

Internally, the issue progression is represented by a `Pipeline`. A `Pipeline` contains multiple `Stages`, each usually corresponds to an `Environment`. A `Stage` contains multiple `Tasks` dealing with a specific database operation such as altering table. A single `Task` can run multiple times (e.g. failed first and then retry). Each run is represented by a `Task Run`.

## Sheet

`Sheet` is the entity where users store, run and share the SQL scripts. A paritcular sheet belongs
to a project and may or may not attach a database context. Users interacts with the Sheet from
[SQL Editor](/docs/sql-editor/manage-sql-scripts).

## CI/CD

See [CI/CD Core Concepts](/docs/change-database/change-workflow/#core-concepts).

0 comments on commit c786875

Please sign in to comment.