This manual documents Octo, the YottaDB Database Management System.

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.

  • It is quick and efficient in pulling data from the YottaDB datastore.

  • It is tightly integrated with the YottaDB object technology that allows for a mix of relational as well as object access to the YottaDB datastore seamlessly. It does not sacrifice one for the other.

  • It aims to provide SQL-92 compliance.


  • Octo uses the PostgreSQL wire protocol, allowing SQL access to YottaDB databases via the PostgreSQL ODBC/JDBC/OLE DB driver.

  • It uses YottaDB local and global variables to hold mapping data, temporary tables, and cross references to provide an efficient relational schema overlay using an augumented SQL DDL language.

  • It uses a 3-phase architecture, consisting of parsing, logical-plan generation and optimization, and physical-plan generation and emission.

  • Rocto is the Remote Octo Server that can communicate with PostgreSQL Server clients.


Octo includes a full set of standard, relational features. These include:

  • The ability to define data structures, especially database schemas. (Data Definition Language, or DDL).

  • The ability to retrieve data. (Data Query Language, or DQL).


At the time of the release of this document, the features to manipulate data (Data Manipulation Language, or DML), manage transactions in the database (Transaction Control Language, or TCL), and control access to data stored in a database (Data Control Language, or DCL) are yet to be implemented.


YottaDB r1.34 or greater is required for successful installation of Octo.

Installing and configuring YottaDB is described on its own documentation page. With the --octo, --posix, --aim options of YottaDB’s script, you can install YottaDB and Octo with one command.


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. Octo requires ydb* environment variables to be defined, and does not recognize the gtm* environment variables. Specifically, it requires ydb_dist to be defined.


Install Prerequisites

Install YottaDB POSIX plugin

The YottaDB POSIX plugin can be installed using the --posix option when installing YottaDB with the ydbinstall script:

./ydbinstall --posix

Alternatively, users can build the POSIX plugin from source:

#In a temporary directory perform the following commands
git clone YDBPosix-master
cd YDBPosix-master
mkdir build && cd build
# Make sure that you have YottaDB environment variables in your shell before continuing
cmake ..
make -j `grep -c ^processor /proc/cpuinfo` && sudo make install

More detailed instructions are on the YottaDB POSIX plugin page.

Install YottaDB AIM plugin

If you did not install the YottaDB AIM plugin (when installing YottaDB) using the --aim option of ydbinstall, build the AIM plugin from source:

# In a temporary directory perform the following commands
git clone
sudo ./

More detailed instructions are on the YottaDB AIM plugin page.

(Optional) Install YottaDB encryption plugin

Installing the YottaDB encryption plugin enables TLS support (Recommended for production installations). You will need to make sure TLS/SSL is enabled for the driver in the client software chosen.

The YottDB encryption plugin can be installed by adding the --encplugin option when installing YottaDB with the ydbinstall script:

./ydbinstall --encplugin

Alternatively, users can build the encryption plugin from source:

# In a temporary directory perform the following commands
sudo tar -xf $ydb_dist/plugin/gtmcrypt/source.tar
# Make sure that you have YottaDB environment variables in your shell before continuing
sudo ydb_dist=$ydb_dist make -j `grep -c ^processor /proc/cpuinfo`
sudo ydb_dist=$ydb_dist make install

Install Octo

Octo is a continuously updated YottaDB plugin that is distributed as source code. A CI (Continuous Integration) pipeline runs a considerable number of unit and system tests before allowing any source code to be merged. This ensures that the master branch is always current with the latest production-ready source code. Octo can be installed by using the --octo option when installing YottaDB with the ydbinstall script. Alternatively, you can build it from source.

Install Prerequisite Packages

# Ubuntu Linux OR Raspbian Linux OR Beagleboard Debian
sudo apt-get install --no-install-recommends build-essential cmake bison flex xxd libreadline-dev libssl-dev

# CentOS Linux OR RedHat Linux
# Note: epel-release has to be installed before cmake3 is installed
sudo yum install epel-release
sudo yum install cmake3 bison flex readline-devel vim-common libconfig-devel openssl-devel

(Optional) Prerequisites for Automated Regression Testing


As we run the automated regression tests on every Octo source code update, install and run BATS only if you are an advanced user who wants to contribute to Octo or run on a Linux distribution on which YottaDB is Supportable but not Supported.

  1. Octo uses BATS for automated integration and regression testing. To use BATS to run tests on Octo, BATS version 1.1+ must be installed:

    git clone
    cd bats-core
    sudo ./ /usr

    This will install BATS to /usr/bin. Note that installing to /usr may require root access or use of sudo. To specify an alternative path change the argument to your preferred location, e.g. “/usr/local” to install to /usr/local/bin.

    Details available in the BATS source repo.

    Some bats tests also require go, java and expect. To run these, the appropriate libraries must be installed:

    # Ubuntu Linux OR Raspbian Linux OR Beagleboard Debian
    sudo apt-get install --no-install-recommends default-jdk expect golang-go
    #CentOS Linux or RedHat Linux
    sudo yum install java-latest-openjdk expect golang

    Additionally, some tests requires a JDBC driver. The JDBC driver must be downloaded to the build directory and JDBC_VERSION must be set in the environment. Versions starting with 42.2.6 are tested, but earlier versions may work. For example, 42.2.12 is the latest release at the time of writing:

    export JDBC_VERSION=42.2.12
  2. Install the en_US.utf8 locale

    Octo tests should be run with the en_US.utf8 locale due to collation order differences in other locales that cause some test outputs to not match reference outputs.

# Debian
locale -a
# if "en_US.utf8" does not appear among the available locales listed by the above command, proceed to the steps below:
sudo vi /etc/locale.gen # or use your preferred text editor
# Uncomment the line in /etc/locale.gen that reads "en_US.UTF-8 UTF-8", then save and exit
sudo locale-gen
  1. (Optional) Install cmocka unit testing framework

    Octo uses cmocka for automated unit testing. To build and run Octo’s unit tests, cmocka must be installed:

    # Ubuntu Linux OR Raspbian Linux OR Beagleboard Debian
    sudo apt-get install --no-install-recommends libcmocka-dev
    # CentOS Linux OR RedHat Linux
    sudo yum install libcmocka-devel
  2. (Optional) Install PostgreSQL client (psql)

    Octo uses the psql PostgreSQL for some integration/regression tests. To build and run these tests, psql must be installed:

    # Ubuntu Linux OR Raspbian Linux OR Beagleboard Debian
    sudo apt-get install --no-install-recommends postgresql-client
    # CentOS Linux OR RedHat Linux
    sudo yum install postgresql
  3. (Optional) Install PostgreSQL server

    Octo uses the PostgreSQL server for some integration/regression tests. To build and run these tests, PostgreSQL must be installed:

    # Ubuntu Linux OR Raspbian Linux OR Beagleboard Debian
    sudo apt-get install --no-install-recommends postgresql
    # CentOS Linux OR RedHat Linux
    sudo yum install postgresql

    Additionally, PostgreSQL must be set up for the user who will be running the tests:

    sudo -u postgres createuser [username]
    sudo -u postgres psql <<PSQL
    alter user [username] createdb;
  4. (Optional) Install UnixODBC and the Postgres ODBC Shared Library

    Octo runs ODBC driver tests if the UnixODBC package is installed. To build and run these tests, you need to do the following:

    # Ubuntu Linux OR Raspbian Linux OR Beagleboard Debian
    sudo apt-get install unixodbc odbc-postgresql
    # CentOS 8 Linux OR RedHat 8 Linux (names on 7 differ slightly)
    sudo yum install unixODBC postgresql-odbc
  5. (Optional - CentOS/RHEL7 only) Install Perl

    On CentOS 7 and RHEL7, Octo test queries sometimes produce output with superfluous escape sequences. These escape sequences are removed by a Perl script, making Perl a dependency for Octo testing on these platforms.

    To install Perl on CentOS 7 or RHEL7:

    # CentOS Linux or RedHat Linux
    sudo yum install perl

Clone the Octo source code repository

# In a temporary directory perform the following commands
git clone YDBOcto-master
cd YDBOcto-master

Compile Octo

mkdir build ; cd build
cmake -DCMAKE_INSTALL_PREFIX=$ydb_dist/plugin .. # for CentOS/RedHat use cmake3 instead
make -j `grep -c ^processor /proc/cpuinfo`

Most users proceed to the Install Octo step below. The instructions here are for those wishing to contribute to Octo, or building it on Supportable but not Supported platforms.

To generate a Debug build instead of a Release build (the default), add -DCMAKE_BUILD_TYPE=Debug to the CMake line above.

To additionally disable the generation of installation rules for the make install, add -DDISABLE_INSTALL=ON. This can be useful when doing testing in a temporary build directory only.

To build the full test suite rather than a subset of it, the FULL_TEST_SUITE option needs to be set to ON, e.g. cmake -D FULL_TEST_SUITE=ON ... In addition, there is a speed test that can be enabled by cmake -D TEST_SPEED=ON. The speed test is intended for use in benchmarking and needs to be run separately from the full test suite. Run it with bats -T bats_tests/test_speed.bats or with the equivalent command ctest -V -R test_speed.

To show the output of failed tests, export the environment variable CTEST_OUTPUT_ON_FAILURE=TRUE. Alternatively, you can show output for only a single run by passing the argument to make: make CTEST_OUTPUT_ON_FAILURE=TRUE test.

Install Octo

Install Octo:

# Tell git that this repo is safe to run git in as root
# Don't forget the -E with sudo; otherwise the git config command has no effect
git config --global --add $(git rev-parse --show-toplevel)
sudo -E make install

Redefine environment variables to include newly installed files:

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


New Octo installations include a default octo.conf configuration file at $ydb_dist/plugin/octo/octo.conf, which may be modified post-install. Re-installing Octo will not overwrite an existing octo.conf in this location, so modifications to this file will be preserved across installations.

Configure Octo

Setup environment variables

The following environment variables must be set for Octo to operate properly:

  • ydb_dist

  • ydb_gbldir

  • ydb_routines

  • ydb_xc_octo

  • ydb_xc_ydbposix

The environment variables ydb_dist, ydb_gbldir, and ydb_routines can initially be set by sourcing ydb_env_set in your YottaDB installation directory. Additional modifications to ydb_routines may be needed due to configuration in octo.conf described later in this manual.

Example setting of the environment variables (assuming default paths):

source /usr/local/lib/yottadb/r1.28/ydb_env_set
export ydb_routines="$ydb_dist/plugin/octo/o/ $ydb_routines"
export ydb_xc_ydbposix=$ydb_dist/plugin/ydbposix.xc
export ydb_xc_octo=$ydb_dist/plugin/octo/ydbocto.xc  # Allow usage of some SQL functions, e.g. DATE_FORMAT()

Setup Database

Octo uses several global variables for its operation, which start with %ydbocto and %ydbAIM. The %ydbAIM globals are intended to be ephemeral and are not recommended to be journaled; we also recommend that you use a memory mapped region with 2K blocks. Use GDE to map %ydbocto* and %ydbAIM global variables to a separate region. Global variables used by Octo and AIM must have NULL_SUBSCRIPTS=ALWAYS.

The following example creates an OCTO database region with the recommended setting in the $ydb_dir/$ydb_rel/g directory and assumes an existing application global directory at $ydb_dir/$ydb_rel/g/yottadb.gld. For more information on setting up a database in YottaDB, refer to the Administration and Operations Guide, and the YottaDB Acculturation Guide for self-paced exercises on YottaDB DevOps.

$ echo $ydb_dir $ydb_rel
/tmp/test r1.30_x86_64
$ $ydb_dist/yottadb -run GDE
%GDE-I-LOADGD, Loading Global Directory file
%GDE-I-VERIFY, Verification OK

GDE> add -segment OCTO -access_method=BG -file_name="$ydb_dir/$ydb_rel/g/octo.dat"
GDE> add -region OCTO -dynamic=OCTO -null_subscripts=ALWAYS -key_size=1019 -record_size=300000 -journal=(before,file="$ydb_dir/$ydb_rel/g/octo.mjl")
GDE> add -name %ydbocto* -region=OCTO
GDE> add -segment AIM -access_method=MM -allocation=20000 -block_size=2048 -extension_count=20000 -file_name="$ydb_dir/$ydb_rel/g/aim.dat"
GDE> add -region AIM -dynamic=AIM -null_subscripts=true -key_size=992 -record_size=1008
GDE> add -name %ydbAIM* -region=AIM
GDE> verify
%GDE-I-VERIFY, Verification OK

GDE> exit
%GDE-I-VERIFY, Verification OK

%GDE-I-GDUPDATE, Updating Global Directory file
$ $ydb_dist/mupip create -region=OCTO
%YDB-I-DBFILECREATED, Database file /tmp/test/r1.30_x86_64/g/octo.dat created
$ $ydb_dist/mupip create -region=AIM
%YDB-I-DBFILECREATED, Database file /tmp/test/r1.30_x86_64/g/aim.dat created
$ $ydb_dist/mupip set -journal=before,enable,on -region OCTO
%YDB-I-JNLCREATE, Journal file /tmp/test/r1.30_x86_64/g/octo.mjl created for region OCTO with BEFORE_IMAGES
%YDB-I-JNLSTATE, Journaling state for region OCTO is now ON

The commands in the example above are reproduced below, to facilitate copying and pasting.

echo $ydb_dir $ydb_rel
$ydb_dist/yottadb -run GDE
add -segment OCTO -access_method=BG -file_name="$ydb_dir/$ydb_rel/g/octo.dat"
add -region OCTO -dynamic=OCTO -null_subscripts=ALWAYS -key_size=1019 -record_size=300000 -journal=(before,file="$ydb_dir/$ydb_rel/g/octo.mjl")
add -name %ydbocto* -region=OCTO
add -segment AIM -access_method=MM -allocation=20000 -block_size=1024 -extension_count=20000 -file_name="$ydb_dir/$ydb_rel/g/aim.dat"
add -region AIM -dynamic=AIM -null_subscripts=true -key_size=992 -record_size=1008
add -name %ydbAIM* -region=AIM
$ydb_dist/mupip create -region=OCTO
$ydb_dist/mupip create -region=AIM
$ydb_dist/mupip set -journal=before,enable,on -region OCTO

(Optional) Test with dummy data using Octo

You can use the Northwind sample database to get started. The dummy data set can be found in the tests/fixtures subdirectory of the YDBOcto repository created by git clone YDBOcto-master.

A dummy data set consists of a .zwr file and a .sql file. The former contains the actual data to be stored in YottaDB, while the latter contains a schema that maps relational SQL structures (tables and columns) to the NoSQL data contained in YottaDB. Assuming that /tmp/YDBOcto-master is the directory from the git clone YDBOcto-master command :

# Unset all ydb_*, gtm* and GTM* environment variables:
unset `env | grep -Ei ^\(\(gtm\)\|\(ydb\)\) | cut -d= -f 1`
export ydb_chset=UTF-8
# Source ydb_* variables:
source $(pkg-config --variable=prefix yottadb)/ydb_env_set
# ydb_dir can optionally be set to use a location other than $HOME/.yottadb for the working environment.

mupip load /tmp/YDBOcto-master/build/tests/fixtures/northwind.zwr
octo -f /tmp/YDBOcto-master/build/tests/fixtures/northwind.sql

Once loaded, you can run octo to start the Octo interactive shell and use SELECT queries to access the data.

Sample Queries

Given below are some sample queries that can be run in Octo once the northwind data set has been loaded.

The following query selects only the DISTINCT values from the ‘Country’ column in the ‘Suppliers’ table.


The following query selects the first five records from the ‘Customers’ table where the country is ‘France’.

OCTO> WHERE Country='France'
7|Blondel père et fils|Frédérique Citeaux|24, place Kléber|Strasbourg|67000|France
9|Bon app'|Laurence Lebihans|12, rue des Bouchers|Marseille|13008|France
18|Du monde entier|Janine Labrune|67, rue des Cinquante Otages|Nantes|44000|France
23|Folies gourmandes|Martine Rancé|184, chaussée de Tournai|Lille|59000|France
26|France restauration|Carine Schmitt|54, rue Royale|Nantes|44000|France

The following query selects all products from the ‘Products’ table with a ProductName that starts with ‘L’.

OCTO> WHERE ProductName LIKE 'L%';
65|Louisiana Fiery Hot Pepper Sauce|2|2|32 - 8 oz bottles|21.05
66|Louisiana Hot Spiced Okra|2|2|24 - 8 oz jars|17
67|Laughing Lumberjack Lager|16|1|24 - 12 oz bottles|14
74|Longlife Tofu|4|7|5 kg pkg.|10
76|Lakkalikööri|23|1|500 ml |18

The following query displays the average price of Products per Category.

OCTO> SELECT AVG(Price), CategoryID
OCTO> FROM Products

The following query displays each Product with its Category and Supplier in ascending order of the ‘SupplierName’.

OCTO> SELECT Products.ProductName, Categories.CategoryName, Suppliers.SupplierName
OCTO> FROM ((Products
OCTO> INNER JOIN Categories ON Products.CategoryID = Categories.CategoryID)
OCTO> INNER JOIN Suppliers ON Products.SupplierID = Suppliers.SupplierID)
OCTO> ORDER BY Suppliers.SupplierName;
Côte de Blaye|Beverages|Aux joyeux ecclésiastiques
Chartreuse verte|Beverages|Aux joyeux ecclésiastiques
Sasquatch Ale|Beverages|Bigfoot Breweries
Steeleye Stout|Beverages|Bigfoot Breweries
Laughing Lumberjack Lager|Beverages|Bigfoot Breweries
Queso Cabrales|Dairy Products|Cooperativa de Quesos 'Las Cabras'
Queso Manchego La Pastora|Dairy Products|Cooperativa de Quesos 'Las Cabras'
Escargots de Bourgogne|Seafood|Escargots Nouveaux
Chais|Beverages|Exotic Liquid
Chang|Beverages|Exotic Liquid
Aniseed Syrup|Condiments|Exotic Liquid
Gorgonzola Telino|Dairy Products|Formaggi Fortini s.r.l.
Mascarpone Fabioli|Dairy Products|Formaggi Fortini s.r.l.
Mozzarella di Giovanni|Dairy Products|Formaggi Fortini s.r.l.
Sirop d'érable|Condiments|Forêts d'érables
Tarte au sucre|Confections|Forêts d'érables
Manjimup Dried Apples|Produce|G'day, Mate
Filo Mix|Grains/Cereals|G'day, Mate
Perth Pasties|Meat/Poultry|G'day, Mate
Raclette Courdavault|Dairy Products|Gai pâturage
Camembert Pierrot|Dairy Products|Gai pâturage
Grandma's Boysenberry Spread|Condiments|Grandma Kelly's Homestead
Uncle Bob's Organic Dried Pears|Produce|Grandma Kelly's Homestead
Northwoods Cranberry Sauce|Condiments|Grandma Kelly's Homestead
NuNuCa Nuß-Nougat-Creme|Confections|Heli Süßwaren GmbH & Co. KG
Gumbär Gummibärchen|Confections|Heli Süßwaren GmbH & Co. KG
Schoggi Schokolade|Confections|Heli Süßwaren GmbH & Co. KG
Maxilaku|Confections|Karkki Oy
Valkoinen suklaa|Confections|Karkki Oy
Lakkalikööri|Beverages|Karkki Oy
Singaporean Hokkien Fried Mee|Grains/Cereals|Leka Trading
Ipoh Coffee|Beverages|Leka Trading
Gula Malacca|Condiments|Leka Trading
Rűgede sild|Seafood|Lyngbysild
Tourtière|Meat/Poultry|Ma Maison
Pâté chinois|Meat/Poultry|Ma Maison
Genen Shouyu|Condiments|Mayumi's
Boston Crab Meat|Seafood|New England Seafood Cannery
Jack's New England Clam Chowder|Seafood|New England Seafood Cannery
Chef Anton's Cajun Seasoning|Condiments|New Orleans Cajun Delights
Chef Anton's Gumbo Mix|Condiments|New Orleans Cajun Delights
Louisiana Fiery Hot Pepper Sauce|Condiments|New Orleans Cajun Delights
Louisiana Hot Spiced Okra|Condiments|New Orleans Cajun Delights
Nord-Ost Matjeshering|Seafood|Nord-Ost-Fisch Handelsgesellschaft mbH
Geitost|Dairy Products|Norske Meierier
Gudbrandsdalsost|Dairy Products|Norske Meierier
Flűtemysost|Dairy Products|Norske Meierier
Gustaf's Knäckebröd|Grains/Cereals|PB Knäckebröd AB
Tunnbröd|Grains/Cereals|PB Knäckebröd AB
Gnocchi di nonna Alice|Grains/Cereals|Pasta Buttini s.r.l.
Ravioli Angelo|Grains/Cereals|Pasta Buttini s.r.l.
Pavlova|Confections|Pavlova, Ltd.
Alice Mutton|Meat/Poultry|Pavlova, Ltd.
Carnarvon Tigers|Seafood|Pavlova, Ltd.
Vegie-spread|Condiments|Pavlova, Ltd.
Outback Lager|Beverages|Pavlova, Ltd.
Rössle Sauerkraut|Produce|Plutzer Lebensmittelgroßmärkte AG
Thüringer Rostbratwurst|Meat/Poultry|Plutzer Lebensmittelgroßmärkte AG
Wimmers gute Semmelknödel|Grains/Cereals|Plutzer Lebensmittelgroßmärkte AG
Rhönbräu Klosterbier|Beverages|Plutzer Lebensmittelgroßmärkte AG
Original Frankfurter grüne Soße|Condiments|Plutzer Lebensmittelgroßmärkte AG
Guaraná Fantástica|Beverages|Refrescos Americanas LTDA
Teatime Chocolate Biscuits|Confections|Specialty Biscuits, Ltd.
Sir Rodney's Marmalade|Confections|Specialty Biscuits, Ltd.
Sir Rodney's Scones|Confections|Specialty Biscuits, Ltd.
Scottish Longbreads|Confections|Specialty Biscuits, Ltd.
Inlagd Sill|Seafood|Svensk Sjöföda AB
Gravad lax|Seafood|Svensk Sjöföda AB
Röd Kaviar|Seafood|Svensk Sjöföda AB
Mishi Kobe Niku|Meat/Poultry|Tokyo Traders
Ikura|Seafood|Tokyo Traders
Longlife Tofu|Produce|Tokyo Traders
Zaanse koeken|Confections|Zaanse Snoepfabriek
Chocolade|Confections|Zaanse Snoepfabriek

Use a Docker Container

A Docker image is available on docker hub. This image is built with the following assumptions about the host environment and automatically starts rocto when run by Docker using the commands below.

  • The ydb_env_set script is used to setup the YottaDB environment and creates/expects a specific layout for globals and routines, specifically:

    • a r1.30_x86_64 directory with the following sub directories:

      • g directory which contains at a minimum:

        • yottadb.gld global directory

      • o directory which contains the compiled M code

      • r directory which contains the source M code

    • a r directory which contains the source M code

  • The octo default configuration is used in /opt/yottadb/current/plugin/octo/octo.conf

Starting the Docker Container

To start the Docker container and make rocto available on the host’s network on the default port 1337 (unless octo.conf within the container is configured otherwise):

docker run -it --network=host yottadb/octo:latest-master

To login with the default ydb user use psql and enter ydbrocks when prompted for a password:

psql -U ydb -h localhost -p 1337

If you would like to use YDB data in an existing local directory structure, then issue the docker run command from a directory where the above directory structure is defined. This is needed to mount it as a volume within the Docker container.

docker run -it -v `pwd`:/data yottadb/octo:latest-master

This will then display the rocto log file on stdout. If you would prefer to run the container as a daemon use the -d command line parameter. Also, if you would like to publish the container on specific ports, specify this with the -p option. For example:

docker run -itd -v `pwd`:/data -p 1337:1337 yottadb/octo:latest-master

The logs can then be retrieved using the docker logs command with the container name or ID as an argument.

Getting access to the container

PostgreSQL wire protocol

The rocto server is listening on port 1337 and all of the directions in the above documentation apply.

Command-line access

You can use the docker exec command to get access to the container for more troubleshooting. Example:

docker exec -it {nameOfContainer/IDOfContainer} /bin/bash

Test with dummy data using Rocto

The northwind data set can also be queried using Rocto (Remote Octo server). SQuirreL SQL needs to be configured in order to use Rocto. An alias needs to be created, including the server IP address and port number.

For example:


A username and password should also be added to the alias. This username and password combination must first be added to Octo using the ydboctoAdmin utility:

yottadb -r %ydboctoAdmin add user <username>

For example:

$ydb_dist/yottadb -r %ydboctoAdmin add user myusername
Enter password for user myusername:
Re-enter password for user myusername:
Successfully added user: "myusername"

In a shell with YottaDB and Octo environment variables set, start Rocto using the following command:


Now, in SQuirreL SQL press the Connect button for the alias created. You can now run queries on the northwind data set through SQuirreL SQL.

For example:


Squirrel SQL Sample Screenshot

Complete documentation of SQuirreL set-up can be found in the ROcto Documentation.


Before running Octo/Rocto make sure that the required YottaDB variables are set either by creating your own script or run source $ydb_dist/ydb_env_set.

To use the command-line SQL interpreter run: $ydb_dist/plugin/bin/octo.

To use the PostgreSQL protocol compatible server run $ydb_dist/plugin/bin/rocto.

If you use the octo command line interpreter, history is stored by default in ~/.octo_history. More information is provided in the History document.

Launching Options

Octo has a few options that can be specified when it is launched.


The verbose option specifies the amount of additional information that is provided to the user when commands are run in Octo.


or equivalently,


The number given to the option corresponds to the following levels:






Information about all errors



Additional information useful to log



Includes information useful for debugging



Information logged stepping through actions

When a number level is specified, the verbose output contains all information corresponding to that level as well as the previous levels.

The default verbose level is set to zero(0) (ERROR).

A single -v in the command line puts the verbose level at one(1) (INFO), -vv puts the level at two(2) (DEBUG), and -vvv puts the level at three(3) (TRACE).


octo --verbose=3


OCTO> YDBOcto-master/build $ ./src/octo -vvv
[TRACE] YDBOcto-master/src/octo.c:50 2019-04-10 10:17:57 : Octo started
[ INFO] YDBOcto-master/src/run_query.c:79 2019-04-10 10:17:57 : Generating SQL for cursor 45
[ INFO] YDBOcto-master/src/run_query.c:81 2019-04-10 10:17:57 : Parsing SQL command
Starting parse
Entering state 0
Reading a token: OCTO> Next token is token ENDOFFILE (: )
Shifting token ENDOFFILE (: )
Entering state 15
Reducing stack by rule 8 (line 182):
   $1 = token ENDOFFILE (: )
Stack now 0
[ INFO] YDBOcto-master/src/run_query.c:83 2019-04-10 10:18:00 : Done!
[ INFO] YDBOcto-master/src/run_query.c:89 2019-04-10 10:18:00 : Returning failure from run_query


The dry-run option runs the parser, and performs checks and verifications on data types and syntax, but does not execute the SQL statements. The database is not altered when Octo is run with the --dry-run option.


or equivalently,



octo --dry-run


The emulate option allows the user to specify which SQL database Octo should emulate. Database names should be in all caps. Currently supported emulations are MYSQL and POSTGRES.


or equivalently,

-e <db_name>


octo --emulate=MYSQL


The input-file option takes a file as input to Octo, that commands are then read from.

--input-file=<path to input file>

or equivalently,

-f <input file>


octo --input-file=files/commands.txt

Useful Commands at OCTO>




Exits the prompt


Displays all relations

d tablename

Displays information about columns of specified table

Relation shown will be similar to the following:

OCTO> \d
(26 rows)
Table "NAMES"