YDB Octo

Octo^® is a SQL database engine whose tables are stored in YottaDB global variables (i.e., YottaDB hierarchical key-value nodes). Octo is installed as a YottaDB plugin.

Homepage: https://gitlab.com/YottaDB/DBMS/YDBOcto

Documentation: https://docs.yottadb.com/Octo/

Octo requires YottaDB r1.34 or greater. Installing and configuring YottaDB is described on its documentation page.

NOTE: Octo is a YottaDB application, not an application that runs on the upstream GT.M for which YottaDB is a drop-in upward-compatible replacement.

Quickstart

Install prerequisite packages:

# Ubuntu
sudo apt update && sudo apt install -y --no-install-recommends build-essential cmake bison flex libreadline-dev libssl-dev wget ca-certificates file libelf-dev curl git pkg-config libicu-dev libconfig-dev

# Rocky Linux
sudo yum --enablerepo=powertools install -y gcc make cmake bison flex readline-devel git libconfig-devel pkg-config libicu-devel wget findutils procps file openssl-devel postgresql

# RHEL 8
sudo subscription-manager repos --enable codeready-builder-for-rhel-8-x86_64-rpms
sudo yum install -y gcc make cmake bison flex readline-devel git libconfig-devel pkg-config libicu-devel wget findutils procps file openssl-devel postgresql

Install YottaDB, Octo, and the required POSIX plugin all together:

mkdir /tmp/tmp ; wget -P /tmp/tmp https://gitlab.com/YottaDB/DB/YDB/raw/master/sr_unix/ydbinstall.sh
cd /tmp/tmp ; chmod +x ydbinstall.sh
sudo ./ydbinstall.sh --utf8 --verbose --octo

Note that the --octo option implicitly installs any dependent plugins, such as the POSIX plugin.

./ydbinstall.sh --help gives a full list of its numerous options.

The Octo Developer Documentation provides instructions on building and installing Octo from source.

Test with dummy data using Octo and ROcto

Set the environment variables:

source $(pkg-config --variable=prefix yottadb)/ydb_env_set

Download the dummy data set and load it:

wget https://gitlab.com/YottaDB/DBMS/YDBOcto/-/raw/master/tests/fixtures/northwind.zwr
wget https://gitlab.com/YottaDB/DBMS/YDBOcto/-/raw/master/tests/fixtures/northwind.sql
mupip load northwind.zwr
octo -f northwind.sql

Run a sample query in Octo:

octo
SELECT * FROM Suppliers;

Set up PostgreSQL and create a user:

sudo apt install postgresql-client
yottadb -r %ydboctoAdmin add user test # Enter password when prompted

Run a sample query in ROcto:

rocto &
psql -h localhost -p 1337 -U test # Enter password when prompted
SELECT * FROM Suppliers;

Kill the ROcto process:

kill %1

Using the Docker Images

We provide two docker images, one containing a copy of a Northwind database, and another containing a copy of VistA.

Northwind

To run the docker image containing a copy of the Northwind database, with the Rocto Daemon running on port 1337:

docker run -d --rm -p 1337:1337 --name=rocto download.yottadb.com/yottadb/octo

You can pass a directory on your computer to keep the data in, so you won't lose it when you stop the docker container:

docker run -d -v $HOME/mydata:/data --rm -p 1337:1337 --name=rocto download.yottadb.com/yottadb/octo

To access the data, you can use the Postgres client (or any other compatible client) like this (Username ydb password ydbrocks):

PGPASSWORD=ydbrocks psql -U ydb -h localhost -p 1337

To look at the Rocto log, you can type this:

docker logs rocto

To go to the shell, and access YottaDB or the Octo command line:

docker exec -it rocto su -
yottadb -dir # YottaDB
octo # Octo
exit

To stop the image, simply kill it, as it will autodelete after stopping. Your data will be kept if you mapped a directory on your computer:

docker kill rocto

VistA

The VistA image's instructions can be found on DockerHub here: https://hub.docker.com/r/yottadb/octo-vehu

Building the documentation

Octo's documentation is maintained in reStructuredText (RST) format. Assuming the current working directory is the repository root, the documentation can be built as an html site with the following commands:

cd doc/
make html

When the build is complete, the documentation will be accessible as html files in doc/_build/html.

To clean up after a documentation build, use:

cd doc/
make clean

NOTE: Octo^® is a registered trademark of YottaDB LLC.