# CLI viide

merql sisaldab CLI-i hetktõmmiste tegemiseks, erinevuste arvutamiseks ja liitmiste käivitamiseks otse terminalist. Composer installib selle nimega `vendor/bin/merql`; merql-i lähtekoodi väljavõttes on selle nimi `bin/merql`.

`vendor/bin/merql` töötab sõltuvusena installimisel, sest merql 0.4.1. Varasemad versioonid otsisid Composer autoloaderit ainult paketi enda `vendor/` kataloogist ja ebaõnnestusid, kui merql oli installitud sõltuvusena.

## Kiire alustamine

```bash
# Capture a baseline from your database.
export MERQL_DB_DSN="sqlite:/path/to/db.sqlite"
vendor/bin/merql snapshot base

# Make some changes, then capture again.
vendor/bin/merql snapshot current

# See what changed.
vendor/bin/merql diff base current
```

Kolmesuunaliseks liitmiseks tuleb meie ja nende hetktõmmised teha kahest baasist lahknenud andmebaasist. Suunake `MERQL_DB_DSN` iga hetktõmmise jaoks õigesse andmebaasi:

```bash
# Base: live before the sandbox was copied from it.
MERQL_DB_DSN="sqlite:/data/live.sqlite" vendor/bin/merql snapshot base

# ... copy live.sqlite to sandbox.sqlite, then both databases change ...

MERQL_DB_DSN="sqlite:/data/sandbox.sqlite" vendor/bin/merql snapshot ours
MERQL_DB_DSN="sqlite:/data/live.sqlite" vendor/bin/merql snapshot theirs

# Three-way merge with dry-run preview.
vendor/bin/merql merge base ours theirs --dry-run
```

Kõigi kolme hetktõmmise järjestikune tegemine samast andmebaasist ei sobi liitmiseks: nende hetktõmmis sisaldaks juba meie muudatusi, mistõttu teatatakse igast meie lisatud reast kui konfliktist `insert_insert`.

## Keskkonnamuutujad

CLI loeb andmebaasi ühenduse üksikasjad keskkonnamuutujatest. Ühenduse saate luua kas PDO DSN-stringi või üksikute MySQL parameetrite abil.

### DSN-põhine ühendus

PDO-põhiste ühenduste jaoks kasutage väärtust `MERQL_DB_DSN`. See on soovitatav lähenemine SQLite ja mittestandardsete seadistuste puhul. DSN peab viitama MySQL või SQLite andmebaasile: CLI ei saa teiste andmebaasimootorite jaoks draiverit registreerida.

| Muutuja | Kirjeldus | Näide |
|---|---|---|
| `MERQL_DB_DSN` | Täielik PDO DSN-string | `sqlite:/path/to/db.sqlite` |
| `MERQL_DB_USER` | Kasutajanimi (DSN-i korral valikuline) | `root` |
| `MERQL_DB_PASS` | Parool (DSN-i korral valikuline) | `secret` |

```bash
# SQLite file.
export MERQL_DB_DSN="sqlite:/var/data/myapp.sqlite"

# MySQL via DSN.
export MERQL_DB_DSN="mysql:host=127.0.0.1;dbname=mydb;charset=utf8mb4"
export MERQL_DB_USER="root"
export MERQL_DB_PASS="secret"
```

Kasutage failipõhist SQLite andmebaasi. Iga CLI käsk käivitatakse eraldi protsessis, seega avab `sqlite::memory:` alati uue tühja andmebaasi ning selle hetktõmmis ei sisalda ühtegi tabelit.

### MySQL lühivorm

Kui `MERQL_DB_DSN` pole määratud, kasutab CLI varuvariandina MySQL-põhiseid muutujaid.

| Muutuja | Vaikeväärtus | Kirjeldus |
|---|---|---|
| `MERQL_DB_NAME` | (nõutav) | Andmebaasi nimi |
| `MERQL_DB_HOST` | `127.0.0.1` | MySQL host |
| `MERQL_DB_PORT` | `3306` | MySQL port |
| `MERQL_DB_USER` | `root` | MySQL kasutajanimi |
| `MERQL_DB_PASS` | (tühi) | MySQL parool |
| `MERQL_DB_ADAPTER` | `pdo` | Seadke väärtuseks `mysqli`, et kasutada mysqli-adapterit |

```bash
export MERQL_DB_NAME="wordpress"
export MERQL_DB_HOST="127.0.0.1"
export MERQL_DB_PORT="3306"
export MERQL_DB_USER="root"
export MERQL_DB_PASS="password"
```

## Käsud

### `merql snapshot <name>`

Salvestage keskkonnamuutujates määratud andmebaasi praegune olek nimega hetktõmmisena. See on ainus käsk, mis loob ühenduse andmebaasiga.

```bash
vendor/bin/merql snapshot baseline
```

Väljund:

```
Snapshot 'baseline' saved
Tables: posts, comments, users, settings
```

Hetktõmmised salvestatakse kataloogi `.merql/snapshots/` töökausta all JSON-failidena (vt [Hetktõmmiste talletamine](#snapshot-storage)). Nimi võib sisaldada ainult tähti ja numbreid, sidekriipse ning allkriipse.

Tüüpiline töövoog: tehke enne muudatuste tegemist hetktõmmis ja seejärel teine pärast muudatuste tegemist. Need kaks hetktõmmist on võrdluse või liitmise aluseks.

### `merql diff <base> <current>`

Võrrelge kaht nimega hetktõmmist ja kuvage erinevuste kokkuvõte.

```bash
vendor/bin/merql diff baseline current
```

Väljund:

```
Changeset: baseline -> current
  Inserts: 3
  Updates: 7
  Deletes: 1
```

Mõlemad hetktõmmised peavad juba olemas olema (varem väärtusega `merql snapshot` tehtud). Võrdlus ei vaja andmebaasiühendust, sest see töötab salvestatud hetktõmmisefailidega.

### `merql merge <base> <ours> <theirs>`

Tehke kolme nimega hetktõmmise põhjal kolmesuunaline liitmine.

```bash
vendor/bin/merql merge base ours theirs
```

Väljund:

```
Merge: base + ours + theirs
  Operations: 12
  Conflicts:  0
  Clean:      yes
```

Kõik kolm hetktõmmist peavad juba olemas olema. Liitmine ei vaja andmebaasiühendust, sest see töötab salvestatud hetktõmmisefailidega, ega kirjuta kunagi andmebaasi: CLI-il pole rakendamise käsku. Kasutage liitmistulemuse rakendamiseks käsku PHP API.

CLI ühendab veerutasemel. See ei rakenda TEXT- ega JSON-veergudele lahtritasemel ühendamist, seega on sama veeru kaks erinevat muudatust siin alati konflikt ([#7](https://github.com/inline0/merql/issues/7)). Lahtritasemel ühendamiseks kasutage `ThreeWayMerge` koos `CellMergeConfig`-ga PHP-s.

#### `--dry-run`

Lisage lipp `--dry-run`, et vaadata eelvaates SQL-lauseid, mille ühendamine looks, ilma midagi käivitamata. Laused kirjeldavad, kuidas baasolukorrast ühendatud tulemuseni jõuda, seega sisaldavad need mõlema poole muudatusi.

```bash
vendor/bin/merql merge base ours theirs --dry-run
```

Väljund:

```
Merge: base + ours + theirs
  Operations: 3
  Conflicts:  0
  Clean:      yes

Dry run SQL:
  INSERT INTO `posts` (`id`, `title`, `status`) VALUES ('10', 'New Post', 'draft');
  UPDATE `posts` SET `title` = 'Updated Title' WHERE `id` = '5';
  DELETE FROM `comments` WHERE `id` = '3';
```

## Arenduskäsud

merqli hoidla väljavõttes on `bin/` all rohkem skripte oraaklipõhise testikomplekti jaoks. Need ei kuulu Composer paketti, seega on sõltuvuste paigaldamisel saadaval ainult `vendor/bin/merql`. Käivitage need hoidla juurkataloogist pärast `composer install`.

| Käsk | Kirjeldus |
|---|---|
| `./bin/oracle <name>` | Arvutab stsenaariumi eeldatava ühendamistulemuse |
| `./bin/actual <name>` | Käivitab merqli stsenaariumil ja salvestab väljundi |
| `./bin/compare <name>` | Võrdleb oraakli ja tegelikku väljundit |
| `./bin/test-scenario <name>` | Täielik töövoog: seadistamine, oraakel, tegelik tulemus, võrdlus |
| `./bin/test-regression` | Käivitab kõik stsenaariumid |
| `./bin/test-regression --category clean` | Käivitab ühe kategooria: `clean`, `conflict`, `identity`, `types`, `scale` või `edge` |
| `./bin/test-regression --fast` | Ainult läbimise või nurjumise tulemus, aruanneteta |
| `./bin/verify-compliance` | Täielik vastavusaruanne |
| `./bin/verify-all` | PHPStan + koodistiil + PHPUnit + oraakli regressioonitest |

`bin/test-regression` aktsepteerib ka väärtust `--jobs`, kuid eirab seda praegu ja käivitab stsenaariumid üksteise järel ([#5](https://github.com/inline0/merql/issues/5)). Tundmatu `--category` korral kuvatakse `No scenarios found` ja väljutakse edukalt.

Stsenaariumide ülesehituse kohta vaadake [testimisstrateegiat](https://merql.inline0.dev/et/docs/advanced/testing).

## Väljumisolek

`merql snapshot`, `diff` ja `merge` väljuvad olekuga 1, kui argument puudub; `snapshot` teeb sama ka siis, kui ühendust pole seadistatud. Puuduva hetktõmmise korral lõpeb käsk käsitlemata `SnapshotException`-iga ja nullist erineva olekuga. Tundmatu käsu korral kuvatakse `Unknown command`, kuid praegu väljutakse olekuga 0 ([#3](https://github.com/inline0/merql/issues/3)).

## Hetktõmmiste salvestamine

Hetktõmmised salvestatakse töökataloogi suhtes asukohta `.merql/snapshots/`. Iga hetktõmmis on üks JSON-fail nimega `<name>.json`. Käivitage kõik käsud samast kataloogist, et need leiaksid üksteise hetktõmmised.

CLI-l pole teise asukoha määramiseks valikut ega keskkonnamuutujat ([#8](https://github.com/inline0/merql/issues/8)). Selle kasutamiseks liikuge enne käivitamist teise töökataloogi. Määrake kataloog asukohas PHP enne hetktõmmiste salvestamist või laadimist:

```php
use Merql\Snapshot\SnapshotStore;

SnapshotStore::setDirectory('/var/data/merql-snapshots');
```

Hetktõmmiste failid on teisaldatavad. Saate neid kopeerida arvutite vahel, lisada versioonihaldusse või jagada ühiseks silumiseks. CLI abil salvestatud hetktõmmise saab laadida käsuga `SnapshotStore::load()` rakenduses PHP ja ka vastupidi, kui mõlemad kasutavad sama kataloogi.