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 | |
---|---|
This section is under huge rewriting and will be put up to date soon. Please, do come back and check this soon. |
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
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.
Here is a quick description of the steps needed to make a controller ready to serve requests:
Start the controller using controller.sh or controller.bat (see Section 6.2, “Starting the Controller”).
Start the console using console.sh -t or console.bat -t (see Section 7.2, “Starting the Administration Console”).
Load a configuration file using load <complete-path>/config.xml. The controller configuration files are described in Section 11, “Virtual database configuration”.
Connect to the virtual database with the administrator login using the admin command (see example below).
Enable all backends using the enableAll command.
Come back to the main menu using the quit command.
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> | +--------------------------+-----------------------------------+
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 | |
---|---|
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
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.
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
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
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 | |
---|---|
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. |
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.