7. Administration console

The C-JDBC administration console is now based on JMX technologies. The text mode console is a JMX client based on the standard RMI connector for JMX but you can also use a generic a JMX administration console through HTTP from any web browser to see all the MBeans registered in the cjdbc domain. The graphical console is not fully supported and only the text console is actively maintained.

You can start the graphic interface using the console.sh/.bat script. If your environment does not support graphic interface, it will automatically revert to the text console.

[Note]Note

This section is under huge rewriting and will be put up to date soon. Please, do come back and check this soon.

7.1. Jmx Notifications List

Here is a list of the JMX remote notifications generated by C-JDBC.

  • cjdbc.controller.virtualdatabases.removed a virtual database has been removed.

  • cjdbc.controller.virtualdatabase.added a virtual database has been added to the controller

  • cjdbc.virtualdatabase.dump.list the list of dump files has been updated

  • cjdbc.virtualdatabase.backend.added a backend has been added to the virtual database

  • cjdbc.distributed.controller.added a controller has joined the group

  • cjdbc.virtualdatabase.backend.disabled a backend has been disabled

  • cjdbc.virtualdatabase.backend.enabled a backend has been enabled

  • cjdbc.virtualdatabase.backend.recovering a backend is recovering a dump file

  • cjdbc.virtualdatabase.backend.recovery.failed Recovery of a dump file failed

  • cjdbc.virtualdatabase.backend.replaying.failed Recovery log replay failed

  • cjdbc.virtualdatabase.backend.backingup a backend is backing up

  • cjdbc.virtualdatabase.backend.enable.write a backend is now write enabled

  • cjdbc.virtualdatabase.backend.removed a backend has been removed from the virtual database

  • cjdbc.virtualdatabase.backend.disabling a backend is now in state disabling (finishing pending transactions and pending requests)

  • cjdbc.virtualdatabase.backend.unknown The backend state has been completely lost. Recovery needed

  • cjdbc.virtualdatabase.backend.replaying a backend is replaying requests from the recovery log

7.2. Starting the Administration Console

The bin directory of the C-JDBC distribution contains the scripts to start the console. Unix users must start the console with console.sh -t whereas Windows users have to start console.bat -t.

The console script accepts several options:

  • -d or --debug: show stack trace when error occurs.

  • -f or --file: Use a given file as the source of commands instead of reading commands interactively.

  • -h or --help: displays usage information.

  • -i or --ip: IP address of the host name where the JMX Server hosting the controller is running (the default is '0.0.0.0').

  • -p or --port: JMX/RMI port number of (the default is 1090).

  • -s or --secret: Password for JMX connection.

  • -u or --username: username for JMX connection.

  • -v or --version: displays version information.

  • -t or --text: force the console to start in text mode. By default, it will try to start in graphic mode

For example, console.sh -t -i 192.168.0.1 -p 1234 will connect the console to the controller using the RMI JMX adaptor listening on port 1234 on 192.168.0.1.

The console has an online help that is accessible by typing help at any time.

7.3. Console Quickstart

Here is a quick description of the steps needed to make a controller ready to serve requests:

  1. Start the controller using controller.sh or controller.bat (see Section 6.2, “Starting the Controller”).

  2. Start the console using console.sh -t or console.bat -t (see Section 7.2, “Starting the Administration Console”).

  3. Load a configuration file using load <complete-path>/config.xml. The controller configuration files are described in Section 11, “Virtual database configuration”.

  4. Connect to the virtual database with the administrator login using the admin command (see example below).

  5. Enable all backends using the enableAll command.

  6. Come back to the main menu using the quit command.

  7. Check the configuration using the getInfo command.

Here is an example of a controller configuration and startup:

 
[emmanuel@gre-home bin]$ console.sh -t
Launching the C-JDBC controller console
Initializing Controller module...
Initializing VirtualDatabase Administration module...
Initializing Monitoring module...
Initializing SQL Console module...
C-JDBC driver (v. 2.0) successfully loaded.
  
gre-home:1090 >help
Commands available for the Controller module are:
admin <virtualdatabase name>
   Administrate a virtual database
connect controller <controller hostname> <jmx port>
   Connect to a C-JDBC controller
drop virtualdatabase <virtualdatabase name>
   Drop a virtual database from the controller
help
   Print this help message
history [<commandIndex>]
   Display history of commands for this module
load virtualdatabase config <virtualdatabase xml file>
   Send a virtual database XML configuration file to the controller and load it
monitor <virtualdatabase name>
   Monitor a virtual database
quit
   Quit this console
reload logging configuration
   Refresh the trace system by reloading the logging configuration file
save configuration
   Save the current configuration of the virtual databases as an XML file
show controller config
   Show Controller configuration
show logging config
   Show logging configuration and the most recent traces
show virtualdatabases
   Show the names of the virtual databases for this controller
shutdown [mode]
   Shutdown the controller and all its virtual databases. Mode parameter must be:
        1 -- wait for all client connections to be closed, does not work with a connection pool
        2 -- mode safe, default value, waits for all current transactions to complete
        3 -- mode force, immediate shutdown without consistency: recovery will be needed on restart
sql client <c-jdbc url>
   Open a SQL client console for the virtual database specified by the C-JDBC URL
upload driver <driver file>
   Upload a driver to the controller

gre-home:1090 > <userinput>show virtualdatabases</userinput>
myDB
gre-home:1090 > <userinput>admin myDB</userinput>
Virtual database Administrator Login > <userinput>admin</userinput>
Virtual database Administrator Password > <userinput>*****</userinput>
Ready to administrate virtual database myDB
myDB(admin) > help
Commands available for the VirtualDatabase Administration module are:
backup <backend name> <dump name> <backuper name> <path> [<tables>]
   Backup a backend into a dump file and associate a checkpoint with this dump
delete dump <dump name>
   Delete a dump
disable <backend name | *>
   Disable the specified backend and automatically set a checkpoint
        * means that all backends of this virtual database must be disabled
enable <backend name | *>
   Enable the specified backend
        * means that all backends of this virtual database must be enabled
expert <on|off>
   Switch to expert mode (commands for advanced users are available)
help
   Print this help message
history [<commandIndex>]
   Display history of commands for this module
quit
   Quit this console
restore <backend name> <dump name> [<tables>]
   Starts the recovery process of the given backend for a given dump name
show backend <backend name | *>
   Show information on backend of this virtual database
        * means to show information for all the backends of this virtual database
show backends
   Show the names of the backends of this virtual database on the current controller
show backupers
   Show the backupers available for backup
show controllers
   Show the names of the controllers hosting this virtual database
show dumps
   Show all dumps available for database recovery
show virtualdatabase config
   Show the XML configuration of the virtual database
transfer dump <dump name> <controller name> [nocopy]
   Make a dump available for restore on another controller.
Optional 'nocopy' (default: false) flag specifies not to copy the dump.

myDB(admin) > <userinput>show backend *</userinput>
+--------------------------+-----------------------------------+
| Backend Name             | localhost                         |
| Driver                   | org.hsqldb.jdbcDriver             |
| URL                      | jdbc:hsqldb:hsql://localhost:9001 |
| Active transactions      | 0                                 |
| Pending Requests         | 0                                 |
| Read Enabled             | true                              |
| Write Enabled            | true                              |
| Is Initialized           | true                              |
| Static Schema            | false                             |
| Connection Managers      | 1                                 |
| Total Active Connections | 5                                 |
| Total Requests           | 0                                 |
| Total Transactions       | 0                                 |
| Last known checkpoint    | <unknown>                         |
+--------------------------+-----------------------------------+
| Backend Name             | localhost2                        |
| Driver                   | org.hsqldb.jdbcDriver             |
| URL                      | jdbc:hsqldb:hsql://localhost:9002 |
| Active transactions      | 0                                 |
| Pending Requests         | 0                                 |
| Read Enabled             | true                              |
| Write Enabled            | true                              |
| Is Initialized           | true                              |
| Static Schema            | false                             |
| Connection Managers      | 1                                 |
| Total Active Connections | 5                                 |
| Total Requests           | 0                                 |
| Total Transactions       | 0                                 |
| Last known checkpoint    | <unknown>                         |
+--------------------------+-----------------------------------+

      

7.4. Console Main Menu

The graphical version of the console provides a shell-like history (more precisely a tcsh-like behavior). You can recall a previous command by using the arrow keys (up and down) to browse the history. If you prefix a command by !, the console will browse the history and complete the command with the latest command in the history starting with the command prefix (completion occurs when you press the tab key). In the graphical version, you can also access all the commands of the different module using the right button of the mouse.

[Note]Note

All the commands issued can also be recalled using the history menu in the contextual menu that appears on a right-button click.

Commands available from the console main menu are:

  • admin <virtualdatabase name>: Administrate a virtual database

  • connect controller <controller hostname> <jmx port>: connect to a C-JDBC controller

  • drop virtualdatabase <virtualdatabase name>: Drop a virtual database from the controller

  • help: Print this help message

  • history [<commandIndex>]: Display history of commands for this module

  • load virtualdatabase config <virtualdatabase xml file>: Send a virtual database XML configuration file to the controller and load it

  • monitor <virtualdatabase name>: Monitor a virtual database

  • quit: Quit this console

  • reload logging configuration: Refresh the trace system by reloading the logging configuration file

  • save configuration: Save the current configuration of the virtual databases as an XML file

  • show controller config: Show Controller configuration

  • show logging config: Show logging configuration and the most recent traces

  • show virtualdatabases: Show the names of the virtual databases for this controller

  • shutdown [mode]: shutdown the controller and all its virtual databases.

    Three shutdown modes are provided. If not specified, the default mode is the shutdown mode immediate.

    • Shutdown mode wait (mode 1): wait for all client connections to be closed, does not work if the client uses a connection pool with persistent connections.

    • Shutdown mode safe (mode 2): default value, waits for all current transactions to complete before shutting down. transaction and shutdown.

    • Shutdown mode force (mode 3): does not wait for transactions completion and kill all connections. Backends are disabled without consistency and a full recovery will be needed on restart.

    E.g: shudown 2.

  • sql client <c-jdbc url>: Open a SQL client console for the virtual database specified by the C-JDBC URL

  • upload driver <driver file>: Upload a driver to the controller

7.5. Administrator Menu

Once the configuration file has been loaded on the controller, all backends are in the disabled state. You must enable them all or one by one to allow them to execute requests. C-JDBC does not check that database contents are synchronized and you must ensure that all backends are in a coherent state prior to starting the controller. To ensure that backends remain synchronized on startup, you must use checkpoints (see Section 6.5.2, “Understanding checkpoints”).

If you properly shutdown the controller using the wait or safe mode, database backend states are properly recorded and their state is automatically restored when they are enabled.

7.5.1. Administrator Standard Commands

Standard commands available from the console administrator menu are:

  • backup <backend name> <dump name> <backuper name> <path> [<tables>]: Backup a backend into a dump file and associate a checkpoint with this dump. Note that the console will ask for a login and password to connect to the backend to backup. This is specific to the Backuper that you are using but this should usually be a valid login/password on the database engine that you are backuping. The login must be granted access on all tables from the controller node.

  • delete dump <dump name>: Delete a dump

  • disable <backend name | *> <checkpoint>: Disable the specified backend and store the given checkpoint (* means that all backends of this virtual database must be disabled)

  • enable <backend name | *>: Enable the specified backend from its last known checkpoint (* means that all backends of this virtual database must be enabled)

  • expert <on|off>: Switch to expert mode (commands for advanced users are available)

  • help: Print this help message

  • history [<commandIndex>]: Display history of commands for this module

  • quit: Quit this console

  • restore <backend name> <dump name> [<tables>]: Starts the recovery process of the given backend using the given dump name. Note that the console will ask for a login and password to connect to the backend to restore This is specific to the Backuper that you are using but this should usually be a valid login/password (real login in the C-JDBC terminology) on the database engine that you are restoring. Note that this login must be granted the right to create new databases and tables.

  • show backend <backend name | *>: Show information on backend of this virtual database (* means to show information for all the backends of this virtual database)

  • show backends: Show the names of the backends of this virtual database on the current controller

  • show backupers: Show the backupers available for backup

  • show controllers: Show the names of the controllers hosting this virtual database

  • show dumps: Show all dumps available for database recovery

  • show virtualdatabase config: Show the XML configuration of the virtual database

  • transfer dump <dump name> <controller name>: Transfer a dump from the current controller to another controller. An example is transfer dump dump1 controller2.emic.com:1090

7.5.2. Administrator Expert Commands

Expert commands are not available by default. use the command expert on to make them available.

  • clone backend config <backend from> <backend to> <url> [driverPath=<value>] [driver=<value>] [connectionTestStatement=<value>]: Clone the configuration of a backend in the current virtual database (this virtually allows to add a new backend)

  • disable read <backend name>: Disable read requests on a backend

  • enable read <backend name>: Enable read requests on a backend

  • force checkpoint <backend name> <checkpoint name>: Force the last know checkpoint of a disabled backend

  • force disable <backend name | *>: Force the disabling of a backend without storing any checkpoints. The backend will not be in a consistent state after this operation! (* means that all backends of this virtual database must be disabled by force)

  • force enable <backend name | *>: Force the enabling of a backend without checking for checkpoints. This command can break the cluster consistency, only use it if you know what you are doing! (* means that all backends of this virtual database must be enabled by force)

  • force path <dump name> <new path>: Update the path of the dump

  • get backend schema <backend name> <file name>: Display backend schema or save it to a file

  • purge log <checkpoint name>: Purge the recovery log upto specified checkpoint. All the entries of the recovery log prior to that checkpoint will be deleted.

  • restore log <dump name> <controller name>: Copy the local recovery log from the specified checkpoint onto the specified remote controller. All previous recovery log content on the remote controller will be erased.

  • show checkpoints: Show all checkpoints available in the recovery log.

  • transfer backend <backend name> <controller jmx address>: Transfer a backend from a controller to an other controller

7.6. Automated Backup With Jmx

Marc Wick has given an example of a cron file to do a daily backup using the jmx connector in C-JDBC. The complete sources can be found in the example file:DBBackup.java in the jmx directory of the examples.

    JMXServiceURL address = new JMXServiceURL("rmi", host, 0, "/jndi/jrmp");

    Map environment = new HashMap();
    environment.put(Context.INITIAL_CONTEXT_FACTORY,
        "com.sun.jndi.rmi.registry.RegistryContextFactory");
    environment.put(Context.PROVIDER_URL, "rmi://" + host + ":" + port);
    environment.put(JMXConnector.CREDENTIALS, PasswordAuthenticator
        .createCredentials("jmxuser", "jmxpassword"));

    JMXConnector connector = JMXConnectorFactory.connect(address, environment);
    ObjectName db = JmxConstants.getVirtualDbObjectName("databaseName");

    ...
    
    MBeanServerConnection delegateConnection = connector
        .getMBeanServerConnection(subj);

    // we create a proxy to the virtual database
    VirtualDatabaseMBean proxy = (VirtualDatabaseMBean) MBeanServerInvocationHandler
        .newProxyInstance(delegateConnection, db, VirtualDatabaseMBean.class,
            false);

    SimpleDateFormat fmt = new SimpleDateFormat("yyyy_MM_dd");
    String checkpointName = fmt.format(new Date());

    // we disable the backend and set a checkpoint
    proxy.disableBackendForCheckpoint("node1", checkpointName);

    // we call the database specific backup tool for the backup
    runDatabaseBackupTool();

    // we enable the backend again
    proxy.enableBackend("node1");
	

The runDatabaseBackupTool() method is completely open and can call any external program (like pg_dump, mysql_dump...)

[Note]Note

This method does not use octopus and as a consequence, the generated backup cannot be restored on a a different database vendor than the one it was issued from. As a great benefit though, the backup process will gain in speed, and the metadata will be completely conformed to that database vendor.

7.7. Recoverying from a failed controller in distributed mode

In a distributed controller configuration, when a controller goes down, here is the list of action to take to recover the failed controller:

  • If the controller does not have any dump available, connect to a controller that has database dumps and use the transfer dump command to copy the dump to the recovering controller.

  • During its failure, the recovery log of the controller missed queries that were executed by the cluster and it is therefore necessary to re-synchronize its recovery log. This can be achieve using the recover log from the same controller you used to transfer the dump.

  • Once the previous operations are completed, you can safely restore the dump on the backends attached to the controller. Then, enabling the backends will resynchronize them with the other nodes of the cluster.