Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/sokil/php-mongo-migrator
Migrations of MongoDB. Part of @PHPMongoKit
https://github.com/sokil/php-mongo-migrator
migration mongo mongo-migrator mongodb odm php phpmongokit schema-migrations
Last synced: 28 days ago
JSON representation
Migrations of MongoDB. Part of @PHPMongoKit
- Host: GitHub
- URL: https://github.com/sokil/php-mongo-migrator
- Owner: sokil
- License: mit
- Created: 2014-05-31T14:46:13.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2024-01-03T09:42:38.000Z (12 months ago)
- Last Synced: 2024-11-08T02:37:02.689Z (about 1 month ago)
- Topics: migration, mongo, mongo-migrator, mongodb, odm, php, phpmongokit, schema-migrations
- Language: PHP
- Homepage: http://phpmongokit.github.io/
- Size: 444 KB
- Stars: 29
- Watchers: 1
- Forks: 15
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-mongodb - PHPMongo Migrator - Migration tool based on PHPMongo ODM (Libraries / PHP)
- awesome-mongodb - PHPMongo Migrator - Migration tool based on PHPMongo ODM (Libraries / PHP)
README
# Stand With Ukraine πΊπ¦
[](https://github.com/vshymanskyy/StandWithUkraine/blob/main/docs/README.md)
PHPMongo Migrator
==================
Migrations for MongoDB based on [PHPMongo ODM](https://github.com/sokil/php-mongo)
[](https://packagist.org/packages/sokil/php-mongo-migrator)
[](https://packagist.org/packages/sokil/php-mongo-migrator)
[](https://coveralls.io/r/sokil/php-mongo-migrator)
[](https://gitter.im/sokil/php-mongo-migrator?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
Schema not required in MongoDb, so we dont need to create databases, collections or altering them. However there are some cases when migrations required in schemaless databases:
* Creating collections with special parameters, like capped collection;
* Renaming or deleting collections;
* Creating, renaming or deleting fields;
* Creating, changing or deleting indexes;
Requirements
------------
* PHP 5
* PHP 5.3 not supported starting from 2018-10-19
* PHP 5.4 - PHP 5.6
* [PHP Mongo Extension](https://pecl.php.net/package/mongo) 0.9 or above (Some features require >= 1.5)
* PHP 7
* [PHP MongoDB Extension](https://pecl.php.net/package/mongodb) 1.0 or above
* [Compatibility layer](https://github.com/alcaeus/mongo-php-adapter). Please, note some [restrictions](#compatibility-with-php-7)
* HHVM
* HHVM Driver [not supported](https://derickrethans.nl/mongodb-hhvm.html).
Installation
------------
#### Install locally through composer
```
composer require sokil/php-mongo-migrator
```
After installation you will be able to run commands in console by running ./vendor/bin/mongo-migrator command.
#### Install using phive
```
phive install sokil/php-mongo-migrator
```
#### Compatibility with PHP 7
> PHPMongo currently based on old [ext-mongo](https://pecl.php.net/package/mongo) entension.
> To use this ODM with PHP 7, you need to add [compatibility layer](https://github.com/alcaeus/mongo-php-adapter), which implement API of old extension over new [ext-mongodb](https://pecl.php.net/package/mongodb).
> To start using PHPMongo with PHP7, add requirement [alcaeus/mongo-php-adapter](https://github.com/alcaeus/mongo-php-adapter) to composer.
> Restrictions for using ODM with compatibility layer you can read in [known issues](https://github.com/alcaeus/mongo-php-adapter#known-issues) of original adapter.
You need to require adapter:
```
composer require alcaeus/mongo-php-adapter
```
Usage
------
```
$ ./mongo-migrator
Console Tool
Usage:
command [options] [arguments]
Options:
-h, --help Display this help message
-q, --quiet Do not output any message
-V, --version Display this application version
--ansi Force ANSI output
--no-ansi Disable ANSI output
-n, --no-interaction Do not ask any interactive question
-v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
Available commands:
create Create new migration
help Displays help for a command
init Initialize migrations project
list Lists commands
migrate Migrate to specific revision of database
rollback Rollback to specific version of database
status Show status of migrations
```
Initialisation of migrations
----------------------------
Every command run in project root where composer.json and vendor dir placed. First we need to create
new migration project. To do that go to project root and run:
```
vendor/bin/mongo-migrator init
```
This creates config file mongo-migrator.yaml and directory "./migrations", where migrations placed.
Also you can use php config instead of yaml. Just initialise your project with php config format:
```
vendor/bin/mongo-migrator init --configFormat=php
```
You may explicitly define path to conficuration file, and also to migration dir:
```
vendor/bin/mongo-migrator init --configuration=confins/monfo-migrations.yaml --migrationDir=../migrations/mongo
```
If migration dir defined relatively, it points to dir where configuration stored. In example above migrations
dir will be `confins/../migrations/mongo`.
Configuration
-------------
#### Configuration format
YAML configuration file placed in file "./mongo-migrator.yaml". PHP has same structure.
```yaml
default_environment: development
path:
migrations: migrations
environments:
development:
dsn: mongodb://localhost
default_database: test
log_database: test
log_collection: migrations
staging:
dsn: mongodb://localhost
default_database: test
log_database: test
log_collection: migrations
production:
dsn: mongodb://localhost
default_database: test
log_database: test
log_collection: migrations
```
Environment is set of configuration parameters, defined for concrete place, like
development machine, test or production server.
* default_environment - some commands required to know environment, where they executed.
This parameters defines which environment to use if environment not specified.
* path.migrations - path to migrations directory, where migration scripts placed.
* environments - section of environment configs.
Every environment has this parameters:
* environments.*.dsn - DSN which used to connect to mongo server
* environments.*.connectOptions - options of MongoClient, described in [\MongoClient PHP manual](http://php.net/manual/ru/mongoclient.construct.php)
* environments.*.default_database - databse, used if no database specified id migration script
* environments.*.log_database - database, used to store migration log
* environments.*.log_collection - collection of database environments.*.log_database used to store migration log
#### Environment variables in configuration
Any value may be initialised from environment variable:
```yaml
default_environment: common
path:
migrations: "%env(MONGO_MIGRATIONS_PATH)%"
environments:
common:
dsn: "%env(MONGO_DSN)%"
default_database: "%env(MONGO_DEFAULT_DB)%"
log_database: "%env(MONGO_LOG_DB)%"
log_collection: "%env(MONGO_LOG_COLLECTION)%"
```
Creating new revision
---------------------
Now you can create your migration script. Creating new revison:
```
vendor/bin/mongo-migrator create revision_name
```
Name of revision must be in camel case format. For example run ```vendor/bin/mongo-migrator create RevisionName```.
This creates migration script like 20151127093706_RevisionName.php, where "20151127093706"
is revision id and "RevisionName" is revision name.
```
pc:~/php-mongo-migrator$ ./bin/mongo-migrator create RevisionName
New migration created at ~/php-mongo-migrator/migrations/20151127093706_RevisionName.php
```
Class source is:
```php
getDatabase('some_database')
->getCollection('come_collection');
// create new field in all documents of collection
$collection->updateAll(function($operator) {
$operator->set('newField', 'defaultValue')
});
}
public function down()
{
$collection = $this
->getDatabase('some_database')
->getCollection('come_collection');
// create new field in all documents of collection
$collection->updateAll(function($operator) {
$operator->unsetField('newField')
});
}
}
```
Building Phar
-------------
1) Install box using manual at https://github.com/box-project/box2. It must be accessible as `box`
2) Check that `composer` installed and accessible in PATH
3) You may build phar in three modes: unsigned version, signed by OPENSSH (for self test on run) and signed by GPG (for installation through phive)
3.1) To build unsigned version just run make
```
make
````
3.2) To build phar signed with OPENSSH, you need to have own private key.
Copy it to `./keys/private.pem` or generate new one:
```
# Generate new one:
openssl genrsa -des3 -out private.pem 4096
# If you want to remove passphrase
openssl rsa -in private.pem -out private.pem
# generate public
openssl rsa -in private.pem -outform PEM -pubout -out public.pem
```
Then build phar:
```
make openssh-signed
````
3.3) To build phar sighen with GPG for phive, you need to place private key to `./keys/private.ask`:
```
gpg --gen-key
gpg --export-secret-keys [email protected] > keys/private.asc
```
Then build GPG-signed phar:
```
make gpg-signed
````
You may verify phar by public key:
```
$ gpg --verify mongo-migrator.phar.asc mongo-migrator.phar
gpg: Signature made ΡΡ, 22-Π»ΠΈΡ-2018 23:27:46 +0200 EET
gpg: using RSA key F530929F7ED528F0
gpg: issuer "[email protected]"
gpg: Good signature from "Dmytro Sokil " [ultimate]
```
You may build phars both for legacy and new driver by defining `MONGO_DRIVER` env variable:
```
make gpg-signed MONGO_DRIVER=new
make gpg-signed MONGO_DRIVER=legacy
```
If `MONGO_DRIVER` env variable not passed, then `make` will try to detect your driver automatically.
Development
-----------
To start development environment in docker run:
```
./run-docker-cli.sh
```
To use `xdebug`, configure your IDE to use port 9001.
There is sandbox to test commands:
```
cd /phpmongo/tests/
export PHPMONGO_DSN="mongodb://mongodb32"; ../bin/mongo-migrator -vvv status -l 4 -e docker
```
Unit tests
----------
Local tests:
```
composer.phar test
```
Docker tests:
```
./run-docker-tests.sh
```