Справочник за CLI

Преглед като Markdown Редактиране в GitHub Документация за 60c6cc7

merql включва CLI за създаване на моментни снимки, изчисляване на разлики и извършване на сливания директно от терминала. Composer го инсталира като vendor/bin/merql; в копие на хранилището на merql това е bin/merql.

vendor/bin/merql работи и при инсталиране като зависимост, тъй като merql 0.4.1. По-ранните версии търсеха автоматично зареждащия файл Composer само в собствената директория vendor/ на пакета и се проваляха, когато merql беше инсталиран като зависимост.

Бърз старт

Обвивка

# 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

Тристранното сливане изисква нашата и тяхната моментна снимка да са създадени от две бази данни, които са се разклонили от базовата. Насочете MERQL_DB_DSN към правилната база данни за всяка моментна снимка:

Обвивка

# 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

Създаването на трите моментни снимки от една и съща база данни, една след друга, не работи за сливане: тяхната версия вече съдържа промените на нашата и всеки ред, вмъкнат от нашата страна, ще бъде отчетен като конфликт insert_insert.

Променливи на средата

CLI чете подробностите за връзката към базата данни от променливите на средата. Можете да се свържете чрез PDO DSN низ или чрез отделни параметри MySQL.

Връзка чрез DSN

Използвайте MERQL_DB_DSN за връзки, поддържани от PDO. Това е препоръчителният подход за SQLite и нестандартни конфигурации. DSN трябва да сочи към база данни MySQL или SQLite: CLI не може да регистрира драйвер за други машини за бази данни.

Променлива	Описание	Пример
`MERQL_DB_DSN`	Пълен PDO DSN низ	`sqlite:/path/to/db.sqlite`
`MERQL_DB_USER`	Потребителско име (незадължително с DSN)	`root`
`MERQL_DB_PASS`	Парола (незадължителна с DSN)	`secret`

Обвивка

# 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"

Използвайте база данни SQLite, съхранявана във файл. Всяка команда CLI се изпълнява в отделен процес, затова sqlite::memory: винаги отваря нова, празна база данни и нейната моментна снимка не съдържа таблици.

Съкратен запис за MySQL

Когато не е зададена MERQL_DB_DSN, CLI използва резервните променливи, специфични за MySQL.

Променлива	По подразбиране	Описание
`MERQL_DB_NAME`	(задължително)	Име на базата данни
`MERQL_DB_HOST`	`127.0.0.1`	Хост на MySQL
`MERQL_DB_PORT`	`3306`	Порт на MySQL
`MERQL_DB_USER`	`root`	Потребителско име за MySQL
`MERQL_DB_PASS`	(празно)	Парола за MySQL
`MERQL_DB_ADAPTER`	`pdo`	Задайте `mysqli`, за да използвате адаптера mysqli

Обвивка

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"

Команди

`merql snapshot <name>`

Запишете текущото състояние на базата данни, чието име е зададено в променливите на средата, като наименувана моментна снимка. Това е единствената команда, която се свързва с база данни.

Обвивка

vendor/bin/merql snapshot baseline

Изход:

Код

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

Моментните снимки се съхраняват като файлове JSON в .merql/snapshots/ под работната директория (вижте Съхранение на моментни снимки). Името може да съдържа само букви, цифри, тирета и долни черти.

Типичен работен процес: създайте моментна снимка преди промените и след това създайте още една. Двете моментни снимки са основата за сравнение или сливане.

`merql diff <base> <current>`

Сравнете две наименувани моментни снимки и покажете обобщение на разликите.

Обвивка

vendor/bin/merql diff baseline current

Изход:

Код

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

И двете моментни снимки трябва вече да съществуват (създадени по-рано с merql snapshot). Сравнението не изисква връзка с база данни, тъй като работи със запазени файлове с моментни снимки.

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

Извършете тристранно сливане на три наименувани моментни снимки.

Обвивка

vendor/bin/merql merge base ours theirs

Изход:

Код

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

И трите моментни снимки трябва вече да съществуват. Сливането не изисква връзка с база данни, тъй като работи със запазени файлове с моментни снимки, и никога не записва в база данни: CLI няма команда за прилагане. Използвайте PHP API, за да приложите резултат от сливане.

CLI извършва сливане на ниво колона. Не слива на ниво клетка колони от тип TEXT или JSON, затова две различни промени в една и съща колона винаги са конфликт (тук: #7). Използвайте ThreeWayMerge с CellMergeConfig в PHP за сливане на ниво клетка.

`--dry-run`

Добавете флага --dry-run, за да прегледате инструкциите SQL, които сливането би генерирало, без да изпълнявате нищо. Инструкциите описват как базовото състояние да се превърне в слетия резултат и затова включват промените и от двете страни.

Обвивка

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

Изход:

Код

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';

Команди за разработка

Копието на хранилището на merql съдържа още скриптове в bin/ за тестовия набор, управляван от оракул. Те не са част от пакета Composer, затова при инсталиране като зависимост разполагате само с vendor/bin/merql. Изпълнявайте ги от основната директория на хранилището след composer install.

Команда	Описание
`./bin/oracle <name>`	Изчислява очаквания резултат от сливането за даден сценарий
`./bin/actual <name>`	Изпълнява merql за даден сценарий и записва изхода
`./bin/compare <name>`	Сравнява изхода от оракула с действителния изход
`./bin/test-scenario <name>`	Пълен процес: настройка, оракул, действителен резултат, сравнение
`./bin/test-regression`	Изпълнява всички сценарии
`./bin/test-regression --category clean`	Изпълнява една категория: `clean`, `conflict`, `identity`, `types`, `scale` или `edge`
`./bin/test-regression --fast`	Само успех/неуспех, без отчети
`./bin/verify-compliance`	Пълен отчет за съответствие
`./bin/verify-all`	PHPStan + стил на кода + PHPUnit + регресия на оракула

bin/test-regression приема и --jobs, но в момента игнорира стойността и изпълнява сценариите един след друг (#5). Непозната --category показва No scenarios found и завършва успешно.

Вижте Стратегия за тестване за структурата на сценариите.

Изходен статус

merql snapshot, diff и merge завършват със статус 1, когато липсва аргумент; snapshot също го прави, когато няма конфигурирана връзка. При липсваща моментна снимка командата се прекратява с необработено изключение SnapshotException и ненулев статус. Непозната команда показва Unknown command, но в момента завършва със статус 0 (#3).

Съхранение на моментни снимки

Моментните снимки се съхраняват в .merql/snapshots/ спрямо работната директория. Всяка моментна снимка е един файл JSON с име <name>.json. Изпълнявайте всички команди от една и съща директория, за да могат да намират моментните снимки една на друга.

CLI няма опция или променлива на средата за друга директория (#8). За да използвате друга директория, преминете към нея, преди да стартирате командата. В PHP задайте директорията преди създаването или зареждането на моментни снимки:

PHP

use Merql\Snapshot\SnapshotStore;

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

Файловете с моментни снимки са преносими. Можете да ги копирате между машини, да ги добавите към система за контрол на версиите или да ги споделите за съвместно отстраняване на грешки. Моментна снимка, създадена от CLI, може да бъде заредена в PHP с SnapshotStore::load(), както и обратното, стига и двете да използват една и съща директория.