Command-line NeXtep

From NeXtep Wiki

1.0.6 : This section refers to neXtep release 1.0.6 and higher

Starting with release 1.0.6, neXtep can be run headless through the command line. The main purpose of this is to allow you to run specific neXtep tasks in contexts where you don't need an IDE (for example during a continuous integration build) or when you cannot run an IDE (for example, when you want to take a snapshot of a production database).

Introduction

Starting with 1.0.6, neXtep provides a command-line API which allows you to take control of the neXtep features from scripts. This way you can automate the build and deployment of any database component, allowing you to continuously integrate your database for example.

Requirements

NeXtep command line client requires a specific distribution of neXtep. You need to install the neXtep headless distribution corresponding to the system where neXtep will run headless and follow the instructions.

Integration

At the moment, no integration with other build tools has been developed. This is our will to be as generic as possible since many tools are able to execute external command-lines. In the future we imagine tight integration with Ant, Maven, NAnt, Hudson, etc.

The task engine

NeXtep offers a set of unitary tasks that you can combine to build your database before running your automated tests. The idea is to let you be able to shift the database to the state you need to run your tests.

Every task can be run through a single command-line program : neXtep-cmd. This command will start the nextep command-line client and can take arguments either from the command line and/or from a property-based configuration file. In any case, arguments are always named the same.

Command-line arguments always override configuration file arguments, so that if you specify an argument on the command line it will be used and any definition of this same argument in the file would be ignored.

Tasks may have mandatory options which need to be defined. The main argument that informs the program of what needs to be done is the tasks option : a comma-seperated list of tasks to run. If any task requires additional arguments, they should be provided or the task will fail.

Here is an example of starting a nextep build task using command line arguments :

./neXtep-cmd.sh -target.user=root -target.database=tutu -target.vendor=MYSQL -tasks=clean

Here is an example of starting a neXtep build task using configuration file :

Configuration file definition :

#build.properties

target.user=root
target.database=tutu
target.vendor=MYSQL

Running a build task :

./neXtep-cmd -config.file=./build.properties -tasks=clean

Best practices

There might be many options to specify to the command-line. When you will get used to the nextep command line client you will see that most options are constants (repository connection settings, export directories), and only some of them change (tasks to run and task-specific options).

A good practice is to mix configuration file and command line arguments :

Put everything which is constant in your configuration file :
- Repository connection settings
- If you always build against a same database, put your target database connection settings in it
- If you build against different databases, you may want to play with several config files
Leave the other options on the command line

Tasks definitions

The following sections will describe every available task with detailed information on the required options and examples of use.

Database cleanup

This action clears an existing database from all its content by dropping every elements from it :

Task code	Task options	Option description
clean	target.user	Connection username of the database to clean
	target.password	Connection password of the database to clean
	target.database	Connection database name to clean
	target.server	Server IP or hostname of the database to clean (default is localhost)
	target.port	Server port of the database to clean (default is vendor default)
	target.vendor	Vendor of the database to clean

Cleanup example

./neXtep-cmd -target.user=root -target.database=tutu -target.vendor=MYSQL -tasks=clean

Installing a set of packaged database version

This action installs a specific module version into the database. The specified version needs to be packaged, meaning that neXtep needs to be able to resolve a delivery chain from current version to specified target version.

Note that you should not run this task after a synchronization task has been performed to the database as it would probably result in errors or mis-deployment.

Task code	Task options	Option description
deploy	target.user	Connection username of the database to deploy to
	target.password	Connection password of the database to deploy to
	target.database	Connection database name to deploy to
	target.server	Server IP or hostname of the database to deploy to (default is localhost)
	target.port	Server port of the database to deploy to (default is vendor default)
	target.vendor	Vendor of the database to deploy to
	repository.user	Connection username of the neXtep repository database
	repository.password	Connection password of the neXtep repository database
	repository.database	NeXtep repository database name
	repository.server	Server IP or hostname of the neXtep repository database
	repository.port	Server port of the neXtep repository database
	repository.vendor	Vendor of the neXtep repository database
	module	Module and version pattern to deploy using the syntax module:version

Specifying the delivery modules to deploy

A few notes about the module option: since neXtep modules can contain spaces, uppercase and/or lowercase, the generic syntax to reference a module has been simplified :

Module names are lower cased : it doesn't matter whether you respect or not the lowercase, neXtep will lower case everything before processing
Spaces are replaced by underscores : this is to simplify command-line grammar by avoiding the need of double quotes

The following neXtep module My Database Module can therefore be referenced as my_wonderful_module in the command line.

The module option contains 2 sections :

The module name
The module version prefix

These 2 parts seperated by ":" consitute the module option.

The version prefix information is a portion of the version to consider. For example, a prefix of 2.0.1 will take every 2.0.1.* versions that it will find in the repository. For example, if you develop an application you may not know which database delivery you need to use, you may not even know that a new database delivery is available. In this case, all you have to do is synchronize the app guys and dba guys on a version prefix (2.0.1 in our example). The application will indicate a dependency to the database module my_wonderful_module:2.0.1, this way any release 2.0.1.0, 2.0.1.1, 2.0.1.2, ... , 2.0.1.x will automatically be deployed during your build !

Deployment example

Command-line :

./neXtep-cmd -target.user=root -target.database=tutu -target.vendor=MYSQL -repository.user=root 
    -repository.database=nextep_repo -repository.vendor=MYSQL -tasks=deploy -module=database_generic_model:1.0.4

Using a properties file to configure the repository :

config.properties

# NeXtep repository definition
repository.user=root
repository.database=nextep_repo
repository.vendor=MYSQL
repository.server=127.0.0.1
repository.port=3306

Then the build could be started using the command-line :

./neXtep-cmd -target.user=root -target.database=tutu -target.vendor=MYSQL -tasks=deploy -module=repository:1.0.4 
    -config=./config.properties

Synchronizing a target database with a workspace's current state

This action performs a synchronization between your integration database and a nextep workspace's current state. The result of the synchronization will be automatically applied. After this task the target database will have the exact state of your repository workspace, whatever the intial state was.

You can apply this action on an empty database or on a pre-existing database.

Task code	Task options
synch	workspace.id : identifier of the neXtep workspace to synchronize workspace.name : name of the neXtep workspace to synchronize

Synchronization example

./neXtep-cmd -target.user=root -target.database=tutu -target.vendor=MYSQL -tasks=synch -workspace.name="nextep_repo"

Generating deliveries

This action materializes deliveries to the filesystem.

Task code	Task options	Option description
materialize	export.directory	Directory location where deliveries should be generated
	module	Module and version pattern to deploy using the syntax module:version
	[matching=STRICT]	Matching strategy of delivery module retrieval for single delivery generation
	repository.user	Connection username of the neXtep repository database
	repository.password	Connection password of the neXtep repository database
	repository.database	NeXtep repository database name
	repository.server	Server IP or hostname of the neXtep repository database
	repository.port	Server port of the neXtep repository database
	repository.vendor	Vendor of the neXtep repository database

Note that the module option follows the exact same rules as defined in the deploy task that installs a delivery module on a target database.

Materialization example