Plugin Reference

This page documents per technology the default object structure, technology-specific configuration directives and all available plugins.

The plugin structure is kept disconnected from the command line interface so it can be easily integrated into other projects. Plugin objects are initialized context-free, meaning you have to pass around configuration and arguments. However, this means you can easily chain plugins and reuse them across projects if you so desire.

In the last section we have included documentation about extending plugins or adding technologies.

Plugin Base Class

class noora.plugins.Plugin.Plugin(connectable=None)

This is the base class to be used by all plugins.

execute(properties, arguments)

The execute method. This should be implemented by subclasses.

Parameters:
  • properties – An initialized noora.system.Properties.Properties class
  • arguments – A dict containing the arguments for execution

MySQL

Objects and directives

A Noora MySQL project can contain one or more databases inside one MySQL instance. When creating a MySQL project, you’ll get the following ddl objects for your initial database, in order of execution (the create_objects directive):

  • tab: Tables are stored here. A table application_properties is added by Noora to manage project properties;
  • fct: Contains functions. A get_property function is added by Noora to manage project properties;
  • trg: Contains triggers. Triggers are added by Noora to manage insert and update actions on the project properties table;
  • idx: Contains indexes. An index for the application_properties table is added by Noora.

The drop_objects directive has the following default list, in order of execution:

  • vw
  • trg
  • tab
  • prc
  • fct
  • idx

The MySQL technology also supports using aliases for your database. Add an alias to the aliasses (sic) list in myproject.json to enable the alias, and add a mapping to the database_aliases list to map a database to an alias, e.g.: "database_aliases": [(foo, foo_bar)].

Connector and Plugins

class noora.connectors.MysqlConnector.MysqlConnector

Connector for MySQL server.

execute(executable, properties)

Execute the script provided by executable on the target server.

Parameters:
  • executable (dict) –

    Should contain the following keys and values:

    • host: The address of the server to connect to;
    • port: Server port to connect to;
    • database: The database name;
    • username: Database username;
    • password: Database user password;
    • script: Path to the script to execute.
  • properties (noora.system.Properties.Properties) – A Noora project properties instance
class noora.plugins.mysql.generate.GeneratePlugin.GeneratePlugin(connectable=None)

This class provides generation functionality for MySQL projects.

execute(properties, arguments)

Create or upgrade a project. The version is always required, the rest only when generating an entirely new project.

Parameters:
  • properties (system.Properties.Properties) – The project properties
  • arguments (dict) –

    This dict contains the plugin arguments:

    • version: (Initial) project version to generate for;
    • host: The hostname for the new project. If not provided, an upgrade is assumed (optional);
    • port: Port to connect to (optional);
    • database: Name of the database (optional);
    • username: Database username (optional);
    • password: Database password (optional).
class noora.plugins.mysql.create.CreatePlugin.CreatePlugin(connectable=None)

Plugin for creating (initializing) a MySQL database.

execute(properties, arguments)

Create a new database instance for the initial version

Parameters:
  • properties (system.Properties.Properties) – The project properties
  • arguments (dict) –

    This dict contains the plugin arguments:

    • host: The hostname where the database will run;
    • database: The database to create in (optional);
    • environment (optional): The environment to create the database in;
    • alias (optional): The database alias. If provided, this will overrule the database argument.
class noora.plugins.mysql.drop.DropPlugin.DropPlugin(connectable=None)

Class providing functionality to drop (clear out) a database.

execute(properties, arguments)

Drop a database after checking if schema and environment are valid values. Also check that host is not on the block list.

Parameters:
  • properties (system.Properties.Properties) – The project properties
  • arguments (dict) –

    This dict contains the plugin arguments:

    • host: The hostname where the database will run;
    • database: The database to create in (optional);
    • environment (optional): The environment to create the database in;
    • alias (optional): The database alias. If provided, this will overrule the database argument.
class noora.plugins.mysql.update.UpdatePlugin.UpdatePlugin(connectable=None)

This class provides functionality for updating a project to a specified version.

execute(properties, arguments)

Update database after checking if schema and environment are valid values. Also check that host is not on the block list and that the version to update to is valid

Parameters:
  • properties (system.Properties.Properties) – The project properties
  • arguments (dict) –

    This dict contains the plugin arguments:

    version: The version to update the database to; host: The hostname that hosts the database to update; database: Database to update (optional); alias: Alias to use (optional); environment: Environment to update the database in (optional).
class noora.plugins.mysql.recreate.RecreatePlugin.RecreatePlugin(connectable=None)

This class provides functionality to drop, create and update a database to a specified version.

execute(properties, arguments)

Drop, create and update the database. Will loop over all versions and initialize the database to the latest version available.

Parameters:
  • properties (system.Properties.Properties) – The project properties
  • arguments (dict) –

    This dict contains the plugin arguments:

    version: Desired target version; host: Hostname to connect to; port: Port to connect to (optional); database: Name of the database (optional); alias: Database alias to use (optional); environment: Name of the environment (optional);

Microsoft SQL

Objects and directives

A Microsoft SQL Server project contains one or more schemas inside one MSSQL Database Instance. When creating a MSSQL project, you’ll get the following ddl objects for your initial database, in order of execution (the create_objects directive):

  • seq: Contains sequences. A sequence for the application_properties table is added by Noora;
  • syn: FIXME
  • tab: Tables are stored here. A table application_properties is added by Noora to manage project properties;
  • cst: FIXME
  • fct: Contains functions. A get_property function is added by Noora to manage project properties;
  • prc: Contains stored procedures.
  • vw: Contains views.
  • trg: Contains triggers. Triggers are added by Noora to manage insert and update actions on the project properties table;
  • idx: Contains indexes. An index for the application_properties table is added by Noora.
  • gra: FIXME

The drop_objects directive has the following default list, in order of execution:

  • vw
  • syn
  • typ
  • tab
  • prc
  • fct
  • seq
  • idx
  • dbl

Connector and Plugins

class noora.connectors.MssqlConnector.MssqlConnector

Connector for Microsoft SQL server.

execute(executable, properties)

Execute the script provided by executable on the target server.

Parameters:
  • executable (dict) –

    Should contain the following keys and values:

    • host: The address of the server to connect to;
    • port: Server port to connect to;
    • database: The database name;
    • schema: The schema to use;
    • username: Database username;
    • password: Database user password;
    • script: Path to the script to execute.
  • properties (noora.system.Properties.Properties) – A Noora project properties instance
class noora.plugins.mssql.generate.GeneratePlugin.GeneratePlugin(connectable=None)

This class provides generation functionality for MSSQL projects.

execute(properties, arguments)

Create or upgrade a project. The version is always required, the rest only when generating an entirely new project.

Parameters:
  • properties (system.Properties.Properties) – The project properties
  • arguments (dict) –

    This dict contains the plugin arguments:

    • version: (Initial) project version to generate for;
    • host: The hostname for the new project. If not provided, an upgrade is assumed (optional);
    • port: Port to connect to (optional);
    • database: Name of the database (optional);
    • schema: Name of the schema (optional);
    • username: Database username (optional);
    • password: Database password (optional).
class noora.plugins.mssql.create.CreatePlugin.CreatePlugin(connectable=None)

Plugin for creating (initializing) a MySQL database.

execute(properties, arguments)

Create a new database instance for the initial version.

Parameters:
  • properties (system.Properties.Properties) – The project properties
  • arguments (dict) –

    This dict contains the plugin arguments:

    • host: The hostname where the database is running;
    • environment: The environment to create the database in (optional).
class noora.plugins.mssql.drop.DropPlugin.DropPlugin(connectable=None)

Class providing functionality to drop (clear out) a database.

execute(properties, arguments)

Drop a database after checking if schema and environment are valid values. Also check that host is not on the block list.

Parameters:
  • properties (system.Properties.Properties) – The project properties
  • arguments (dict) –

    This dict contains the plugin arguments:

    • host: The hostname to drop on;
    • environment: Environment to drop the database from.
class noora.plugins.mssql.update.UpdatePlugin.UpdatePlugin(connectable=None)

This class provides functionality for updating a project to a specified version.

execute(properties, arguments)

Update database after checking if schema and environment are valid values. Also check that host is not on the block list and that the version to update to is valid

Parameters:
  • properties (system.Properties.Properties) – The project properties
  • arguments (dict) –

    This dict contains the plugin arguments:

    • version: The version to update the database to;
    • host: The hostname that hosts the database to update;
    • schema: Schema to update (optional);
    • environment: Environment to update the database in (optional).
class noora.plugins.mssql.recreate.RecreatePlugin.RecreatePlugin(connectable=None)

This class provides functionality to drop, create and update a database to a specified version.

execute(properties, arguments)

Drop, create and update the database. Will loop over all versions and initialize the database to the latest version available.

Parameters:
  • properties (system.Properties.Properties) – The project properties
  • arguments (dict) –

    This dict contains the plugin arguments:

    • version: Desired target version;
    • host: Hostname to connect to;
    • port: Port to connect to (optional);
    • environment: Name of the environment (optional).

PostgreSQL

Objects and directives

A PostgreSQL Server project contains one or more schemas inside one PostgreSQL Database. When creating a project, you’ll get the following ddl objects for your initial database, in order of execution (the create_objects directive):

  • seq: Contains sequences. A sequence for the application_properties table is added by Noora;
  • tab: Tables are stored here. A table application_properties is added by Noora to manage project properties;
  • fct: Contains functions. A get_property function is added by Noora to manage project properties;
  • vw: Contains views.
  • trg: Contains triggers. Triggers are added by Noora to manage insert and update actions on the project properties table;
  • idx: Contains indexes. An index for the application_properties table is added by Noora.

The drop_objects directive has the following default list, in order of execution:

  • vw
  • trg
  • fct
  • tab
  • idx
  • sex

Connector and Plugins

class noora.connectors.PGSQLConnector.PGSQLConnector

Connector for PostgreSQL server.

execute(executable, properties)

Execute the script provided by executable on the target server.

Parameters:
  • executable (dict) –

    Should contain the following keys and values:

    • host: The address of the server to connect to;
    • port: Server port to connect to;
    • database: The database name;
    • username: Database username;
    • password: Database user password;
    • script: Path to the script to execute.
  • properties (noora.system.Properties.Properties) – A Noora project properties instance
class noora.plugins.postgresql.generate.GeneratePlugin.GeneratePlugin(connectable=None)

This class provides generation functionality for MySQL projects.

execute(properties, arguments)

Create or upgrade a project. The version is always required, the rest only when generating an entirely new project.

Parameters:
  • properties (system.Properties.Properties) – The project properties
  • arguments (dict) –

    This dict contains the plugin arguments:

    • version: (Initial) project version to generate for;
    • host: The hostname for the new project. If not provided, an upgrade is assumed (optional);
    • port: Port to connect to (optional);
    • database: Name of the database (optional);
    • schema: Name of the schema (optional);
    • username: Database username (optional);
    • password: Database password (optional).
class noora.plugins.postgresql.create.CreatePlugin.CreatePlugin(connectable=None)

Plugin for creating (initializing) a PostgreSQL database.

execute(properties, arguments)

Create a new database instance for the initial version.

Parameters:
  • properties (system.Properties.Properties) – The project properties
  • arguments (dict) –

    This dict contains the plugin arguments:

    • host: The hostname where the database is running;
    • environment: The environment to create the database in (optional).
class noora.plugins.postgresql.drop.DropPlugin.DropPlugin(connectable=None)

Class providing functionality to drop (clear out) a database.

execute(properties, arguments)

Drop a database after checking if schema and environment are valid values. Also check that host is not on the block list.

Parameters:
  • properties (system.Properties.Properties) – The project properties
  • arguments (dict) –

    This dict contains the plugin arguments:

    • host: The hostname to drop on;
    • environment: Environment to drop the database from.
class noora.plugins.postgresql.update.UpdatePlugin.UpdatePlugin(connectable=None)

This class provides functionality for updating a project to a specified version.

execute(properties, arguments)

Update database after checking if schema and environment are valid values. Also check that host is not on the block list and that the version to update to is valid

Parameters:
  • properties (system.Properties.Properties) – The project properties
  • arguments (dict) –

    This dict contains the plugin arguments:

    • version: The version to update the database to;
    • host: The hostname that hosts the database to update;
    • schema: Schema to update (optional);
    • environment: Environment to update the database in (optional).
class noora.plugins.postgresql.recreate.RecreatePlugin.RecreatePlugin(connectable=None)

This class provides functionality to drop, create and update a database to a specified version.

execute(properties, arguments)

Drop, create and update the database. Will loop over all versions and initialize the database to the latest version available.

Parameters:
  • properties (system.Properties.Properties) – The project properties
  • arguments (dict) –

    This dict contains the plugin arguments:

    • version: Desired target version;
    • host: Hostname to connect to;
    • port: Port to connect to (optional);
    • environment: Name of the environment (optional).

Adding Plugins or Technologies

Creating plugins

Adding a plugin is fairly easy:

  1. Add a package for your plugin by creating noora.plugins.<technology>.<plugin_name>.__init__.py;
  2. Add a plugin class in the module noora.plugins.<technology>.<plugin_name>.<PluginName>Plugin called <PluginName>Plugin;
  3. Make sure your plugin class subclasses the technology’s base plugin class (generally called noora.plugins.<technology>.<Technology>Plugin.<Technology>Plugin);
  4. Lastly, your plugin should have an execute() method that accepts two parameters: properties and arguments which should be of type noora.system.Properties.Properties and dict respectively.

The execute method does not need to return anything and should raise exceptions where applicable.

To enable the new plugin to be called from the command line, make sure to create a cli method inside the plugin package root (noora.plugins.<technology>.<plugin_name>). This method can be a simple click command.

By naming the command cli, it is automatically discovered by the Noora CLI. If your plugin is also usable outside a project scope, you can create a cli_outside_scope command in the plugin package root.

Make sure to add the @click.pass_obj decorator. This will enable the CLI to pass the properties object to the command, which you can in turn pass on to your plugin.

Adding technologies

Adding a technology starts by creating a package inside the noora.plugins package with the name of your new technology. Then, you’ll need to fulfill the following requirements:

  • Add a connector for your technology. See noora.connectors for examples;
  • Add a technology base plugin that inherits noora.plugins.Plugin.Plugin and configures the proper connector to use;
  • Add a generate plugin for the technology with templates for the project configuration and default objects to create. NOTE: the generate plugin should be able to create a new project as well as a new version inside a project;
  • Add the minimally required create, drop and update plugins. The recreate plugin is not required but recommended to implement.