Maintaining s-Server

The three maintenance topics are:

Working with Checkpoints

All SQLstream metadata, and all local data stored in tables associated with the SYSFTRS row store, are stored in an in-memory database.

This data is only saved to a persistent store (a data file) when SQLstream s-Server is shut down gracefully, or when the user explicitly creates a checkpoint as described in User-initiated Checkpoints below.

When SQLstream s-Server is shut down normally, data in the in-memory database is serialized to disk.

This is called a checkpoint.

Both creating or restoring checkpoints can only be done when the server is not running. The checkpoint script will give an error message if you try to run it when the server is also running.

Starting or stopping the server normally involves using checkpoints. Before you start it the first time, the server script creates an initial checkpoint. And when you stop the server normally, it creates a checkpoint immediately after the server stops, then restores from that checkpoint when you restart the server.

How are checkpoints saved?

Checkpoints are saved into the $SQLSTREAM_HOME/catalog/checkpoint directory in the form of a data file.

Previous checkpoints are compressed into a tarball and moved into the $SQLSTREAM_HOME/catalog/checkpoints.old directory.

What happens if the SQLstream s-Server process is killed or cancelled?

Any changes made to local data and to the metadata will be lost.

Specifying a Checkpoint

You can specify an initial checkpoint in /etc/default/s-Serverd. A checkpoint creates a known good point from which SQLstream s-Server can start applying changes recorded to the log when recovering after a crash or unexpected shutdown. This allows you to have the server start on server bootup in a known state.

To do so, add the following line to /etc/default/s-Serverd:

SQLSTREAM_INITIAL_CHECKPOINT=<checkpoint name>

Restarting sserverd from a Checkpoint

To roll back to an old checkpoint when running as a service, copy the desired checkpoint into $SQLSTREAM_HOME/catalog/checkpoint(the default checkpoint) and restart sserverd.

User-initiated Checkpoints

You can manually invoke the checkpointing mechanism. On an installed system, simulate a clean-exit checkpoint by running

$ checkpoint --create

This command creates a tarball backup of the checkpoint directory, and then copies the current catalog to the checkpoint directory. (The checkpoint directory contains the files you need when promoting a SQLstream application from dev to test to production, i.e., the files you would want to move to the target system.)

Working with Named Checkpoints

You can create a named checkpoint to created a named tarball for transfer to the target system. On the source system, enter the following command:

$ checkpoint --createnamed foobar

Then transfer that named tarball to the target system, such as by using a command like the following:

$ scp catalog/checkpoints.named/foobar.tgz \
                   target-system:installed-dir/catalog/checkpoints.named

Once you have done so, you can restore the entire checkpoint on the target system by using a command along the following lines:

$ checkpoint --restorenamed foobar

You can use –deleteNamed to delete a named checkpoint. You can also use –listNamed to list named repositories.

Note: The checkpoint script is located in $SQLSTREAM_HOME/bin. It relies on a script called defineAspenRuntime.sh. This script also manages the server and various other utilities, and reads the various environment files for the server, the catalog, and other system elements.

Promoting a SQLstream Application

This approach assumes that the application is represented by the entire content of the SQLstream s-Server repository.

To promote the application, do the following three operations:

  1. Cause a checkpoint to be produced on the source system (for example, by a clean shutdown of SQLstream s-Server or a user-initiated checkpoint.

    A checkpoint backup of the repository is created if you stop the SQLstream s-Server by typing !quit or !kill into the SQLstream s-Server terminal window. (See Starting and Stopping SQLstream s-Server.) Typing Ctrl+C in that window can also stop the server, but does not not create a checkpoint backup of the repository. The next restart of the server will restore the previous checkpoint backup, lacking any changes made to repository objects since that prior backup. Typing Ctrl+C should only be done in extreme circumstances.

  2. Copy the checkpoint files to the target system, replacing the checkpoint there.

  3. Restart SQLstream.

Post Promotion Actions

It may be necessary to modify some elements of the application. For example, to relocate from development to test, alterations may be needed to the URLs or other options for foreign streams, which can be achieved by either of the following two operations:

  1. By (automatically) editing the catalog file before starting SQLstream s-Server, or

  2. By running a SQL script against the catalog once SQLstream s-Server is started.

After doing either 1 or 2, make sure to checkpoint the final definition. Otherwise, if it falls over, you have to do the conversion again. Use a command such as:

$ checkpoint --createnamed finalDefinition

Restoring The Database

A checkpoint is a tarball that contains the SQLstream metadata and local table data as of a specific moment in time. The checkpoint can be created either by a user-initiated or a ‘graceful shutdown’ of the SQLstream engine. A user-initiated checkpoint can be named or not; an automatic checkpoint resulting from a graceful shutdown does not have a name. For more detail, see the topic Starting and Stopping SQLstream s-Server.

Upon restart after a graceful shutdown, SQLstream automatically restores the most recent checkpoint backup. To use a previous named checkpoint, the following command can be used:

$ checkpoint --restorenamed foobar