Ocient Simulator
For development or local workloads with no performance requirements, provides a simulated database system upon request. This system is distributed as a lightweight Docker container that simulates a complete Ocient system with the following features:
- SQL port to connect to via any of Ocient’s supported connectors
- No NVMe drive or Linux huge page requirements
The Ocient Simulator is distributed as a Docker image in compressed tarball format (.tar.gz). Upon receiving the file, it can be loaded into the daemon with the docker load command:
The docker load command will print the name of the loaded image on stdout. If desired, the image can be renamed with docker tag:
For the remainder of these docs, the image name of the Ocient Simulator will be referred to as IMAGE.
The Ocient Simulator requires the following:
- Docker Engine >= 17.03
- 8GB system RAM
- 64-bit Intel® architecture CPU
The recommended invocation of the Ocient Simulator is a docker run command like the following:
Replace IMAGE in the above command with the actual name of your Docker image. Replace CONTAINER in the above command with the name you wish to use to reference your container in future Docker commands.
This invocation detaches the container to run in the background, and binds container port 4050 to port 4050 of the host. The sys_nice capability is explained in Ocient Simulator. The container ID will be printed on stdout once the container is started.
Connecting to and running queries against the Ocient Simulator is done via the Ocient JDBC Driver. See Connecting via JDBC for detailed instructions for using the Ocient JDBC Driver. Note Version Compatibility for the version of the Ocient Simulator in use.
By default, the Ocient Simulator configures the system database and creates the default user with username admin@system user and password admin.
This example assumes that port 4050 on the loopback device of the host system is listening for incoming JDBC connections. If the Ocient Simulator is running on a different machine, use the appropriate IP or hostname to connect.
To reset the system, remove the container and start a new one.
Example:
To reset the system, stop the container and start a new one.
See Ocient Simulator for techniques to preserve data across restarts.
The container exposes additional ports that may be useful depending on the use case for the system:
Exposed Port | Description |
4050 | The JDBC port of the cluster. |
8080 | Ocient Load and Transformation (LAT) service. When you load new data, the LAT client connects to this port. |
9090 and 9091 | The REST interfaces for the SQL and Foundation (LTS) node processes, respectively. |
These ports must be bound as part of the docker run invocation as described in the Docker documentation.
The following environment variables can be set at container runtime to affect certain aspects of the Ocient Simulator.
Environment variable | Description |
ROLEHOSTD_LOG_LEVEL | Sets the rolehostd log level for each node in the cluster. Can be one of error, info, warn, verbose, or debug. Defaults to info. |
NEW_DATA_FILE_SIZE_BYTES | When running the simulator without mounted data, specifies the size in bytes of the data files created. Note that two of these files will be created internally, taking up 2*NEW_DATA_FILE_SIZE_BYTES of disk space. The data files must be large enough for the dataset(s) to be loaded to fit. The created files cannot be resized after creation. Defaults to 1 GiB (1073741824 bytes). |
START_LAT | Starts the LAT tool within the Docker image. |
LAT_MEMORY and LAT_MEMORY_DIRECT | Configure the memory used by the LAT tool when it is running. |
Example:
Docker supports a variety of options that can be provided at container start to limit a container's access to host resources. Refer to the official Docker documentation for the full list of options. This section will explain how constraints on specific host resources affect the Ocient Simulator.
CPU can be safely limited without adverse effects. Most workloads will benefit from having multiple CPU cores available (>=4).
Example:
The Ocient Simulator requires sufficient RAM to execute all workloads. Stability or uptime of the system is not guaranteed in low or out of memory conditions. If you desire to limit the memory of the running Docker container, it is recommended to benchmark the container’s memory usage on your workload, and provide at least 1GB of RAM above the maximum observed.
When limiting memory of the Ocient Simulator, do not use the --oom-kill-disable option, or the database may become unresponsive for a significant period of time after running out of memory.
Example:
As part of normal operation, the Ocient Simulator attempts to set memory and CPU affinity. The error message mbind: Operation not permitted may show up in the logs without the additional sys_nice capability granted to the container. This is a non-fatal error, but can be distracting. Provide the --cap-add=sys_nice argument to docker run on startup to resolve the error.
Example:
All logs from the Ocient Simulator are sent to stdout and stderr and will be sent to the logging driver configured for the host Docker installation or the container. This allows for easy inspection of container logs via the docker logs command. For a full list of options supported by the logging driver in use, consult the documentation.
When using the Docker default logging driver json-file, container logs can be limited with the --log-opt max-size and --log-opt max-file options.
Example:
The easiest way to create tables and add data to the database is to use the CREATE TABLE AS SQL statement. The Ocient database has a built-in data generation table named sys.dummyX where X is an integer that indicates the number of rows in the table. The dummy table contains a single integer column named c1, which contains the row number. However, you can use this table to generate other data types. For example, execute these commands to generate a new table.
Another approach to load data into the database is to use the LAT. The Ocient Simulator can optionally run LAT if you specify the START_LAT=y setting as an environment variable. If the LAT is running, you can use the LAT client to configure and load data from a variety of data sources. For details, see LAT Overview.
To run the Docker container with LAT, specify the START_LAT=y environment variable and bind port 8080 to allow the LAT Client to operate the LAT.
Example:
By default, when you restart the Docker container for the Ocient Simulator, the whole state and all data resets. To preserve data across restarts or to transfer data to other systems, you can store the data in a docker volume. The Docker image stores the whole Ocient Simulator state in the /db directory. To create and use a Docker volume to hold the Ocient Simulator state, use the --volume (-v) parameter with the docker run command to mount the /db directory on a Docker volume. For example:
If you restart the Docker image using the same volume, the system preserves the database state and data.