OpenText Analytics Database images

The following table describes database server and automation tool images:

Using the Vertica-SDK container

Use the prebuilt UDx SDK container image to develop and compile C++ user-defined extensions (UDxs) for OpenText™ Analytics Database.

Prerequisites

• Docker installed and running.
• Access to the vertica-sdk container image.
• A running OpenText™ Analytics Database instance for testing your UDxs.
• Run the make vsdk-exec command from the root of the UDx container (only if you want to use the vsdk-* scripts).

Getting started

1. Set your container image.

   A set of vsdk-* scripts is provided in the UDx-container to assist you throughout the development process. To use these scripts, first clone the repository. Then, set the VSDK_IMAGE environment variable to point to your vertica-sdk container image:

   export VSDK_IMAGE=opentext/vertica-sdk:ubuntu-v25.4.0-0
   

2. Add vsdk scripts to your PATH.

   Download or clone the vsdk-* scripts and add them to your PATH:

   export PATH=/path/to/vertica-containers/UDx-container:$PATH
   

Development workflow

The following outlines the UDx development workflow including available vsdk commands, compiling your UDx, and interactive development:

Available vsdk commands

The following commands are available for UDx development:

  | Command | Description |
  |---------|-------------|
  | `vsdk-bash` | Opens an interactive bash shell in the SDK container |
  | `vsdk-make` | Runs make with your Makefile inside the container |
  | `vsdk-g++` | Compiles C++ code using g++ in the container |
  | `vsdk-cp` | Copies files using the container environment |
  | `vsdk-cleanup` | Removes stopped SDK containers |

Compiling your UDx

Basic Compilation

Navigate to your UDx project directory and use vsdk-make:

cd /path/to/your/udx-project
vsdk-make

This setup:

• Mounts your current directory into the container.
• Mounts your home directory into the container.
• Executes make with your project's Makefile.
• Places the compiled libraries (.so files) to your local directory.

Using vsdk-g++ directly

For simple projects without a Makefile:

vsdk-g++ -o myudx.so -shared -fPIC myudx.cpp \
    -I/opt/vertica/sdk/include \
    -L/opt/vertica/sdk/lib

Interactive Development

Open a bash shell in the SDK container to explore, debug, or manually compile:

vsdk-bash

Inside the container, you have access to:

• /opt/vertica/sdk/ - vertica-sdk headers and examples.
• Your home directory (mounted).
• Your current working directory (mounted).
• All development tools (g++, make, cmake, gdb, and so on).

Compiling SDK examples

# Copy examples to your local directory
vsdk-cp -r /opt/vertica/sdk/examples ./my-examples

# Navigate to the examples directory
cd my-examples

# Build the examples
vsdk-make ScalarFunctions
vsdk-make AggregateFunctions
vsdk-make TransformFunctions

# Compiled libraries will be in ./build/
ls -l build/*.so

Advanced usage

Mounting additional directories

If your build process needs access to files outside your current directory:

VSDK_MOUNT='/usr/local/lib /opt/mytools' vsdk-make

This mounts the specified directories at the same paths in the container.

Using an environment file

Create a file with environment variables for your build:

# build.env
CXX_FLAGS=-O2 -Wall
VERTICA_SDK=/opt/vertica/sdk
BUILD_TYPE=release

Use it with vsdk commands:

VSDK_ENV=build.env vsdk-make

Working with different images

If you work with multiple OpenText™ Analytics Database versions, you can switch between them easily:

# For OpenText™ Analytics Database 24.x development
export VSDK_IMAGE=opentext/vertica-sdk:ubuntu-v24.4.0-0
vsdk-make

# For OpenText™ Analytics Database 25.x development
export VSDK_IMAGE=opentext/vertica-sdk:ubuntu-v25.4.0-0
vsdk-make

Testing your UDx

Load the UDx into OpenText™ Analytics Database

After compiling your UDx, load it into your database:

1. Copy the compiled library to a location accessible by the database.

   If your database is running on Docker:

   docker cp myudx.so vertica-container:/tmp/
   

   If your database is running on Kubernetes:

   kubectl cp myudx.so vertica-pod:/tmp/myudx.so
   
   # Or if you need to specify a specific container in a pod:
   kubectl cp myudx.so vertica-pod:/tmp/myudx.so -c vertica-server
   
   # Or copy to a specific namespace:
   kubectl cp myudx.so namespace/vertica-pod:/tmp/myudx.so
   

2. Load the library in your database:

   CREATE OR REPLACE LIBRARY myudx AS '/tmp/myudx.so' LANGUAGE 'C++';
   

3. Create your UDx function:

   -- For a scalar function
   CREATE OR REPLACE FUNCTION my_function AS 
       LANGUAGE 'C++' 
       NAME 'MyFunctionFactory' 
       LIBRARY myudx;
   

4. Test your function:

   SELECT my_function(column) FROM my_table;
   

Debug your UDx

If you encounter issues:

1. Use vsdk-bash to investigate:

   vsdk-bash
   # Inside container:
   ldd /path/to/myudx.so  # Check library dependencies
   nm -D /path/to/myudx.so  # Check exported symbols
   

2. Compile with debug symbols:

   vsdk-g++ -g -O0 -shared -fPIC myudx.cpp -o myudx.so \
       -I/opt/vertica/sdk/include
   

3. Check logs for runtime errors.

Cleanup

Remove stopped containers to free up disk space:

vsdk-cleanup

This will:

• List all containers created by the vsdk scripts.
• Stop running containers.
• Remove all containers for your SDK image.

Troubleshooting

"ERROR: Set VSDK_IMAGE to opentext/vertica-sdk:..."

You have not set the VSDK_IMAGE environment variable. Set it as shown in Getting Started.

Container doesn't have required tools

The SDK container includes all standard development tools. If you need additional tools, consider:

• Installing them temporarily in an interactive session with sudo apt install (Ubuntu) or sudo yum install (AlmaLinux).
• Creating a custom image based on the SDK image.

Best practices

• Always set VSDK_IMAGE in your environment or shell configuration.
• Keep your source files outside the container. The container is for compilation only.
• Use version control (git) for your UDx source code.
• Test with the same database version that you plan to deploy.
• Clean up containers regularly with vsdk-cleanup.
• Document your build process in a Makefile or README.

Additional Resources

• vertica-sdk documentation
• UDx Examples in /opt/vertica/sdk/examples
• CREATE LIBRARY reference

Python container UDx

The database images with Python UDx development capabilities include the vertica_sdk package and the Python Standard Library.

If your UDx depends on a Python package that is not included in the image, you must make the package available to the database process during runtime. You can either mount a volume that contains the package dependencies, or you can create a custom database server image.

Use the Python Package Index to download Python package source distributions.

Mounting Python libraries as volumes

You can mount a Python package dependency as a volume in the database server container filesystem. A Python UDx can access the contents of the volume at runtime.

1. Download the package source distribution to the host machine.

2. On the host machine, extract the tar file contents into a mountable volume:

   $ tar -xvf lib-name.version.tar.gz -C /path/to/py-dependency-vol
   

3. Mount the volume that contains the extracted source distribution in the custom resource (CR). The following snippet mounts the py-dependency-vol volume in the database server container:

   spec:
     ...
     volumeMounts:
     - name: nfs
       mountPath: /path/to/py-dependency-vol
     volumes:
     - name: nfs
       nfs:
         path: /nfs
         server: nfs.example.com
     ...
   

   For details about mounting custom volumes in a CR, see VerticaDB custom resource definition.

Adding a Python library to a custom database image

Create a custom image that includes any Python package dependencies in the database server base image.

For a comprehensive guide about creating a custom database image, see the Creating a Vertica Image tutorial in the Vertica Integrator's Guide.

1. Download the package source distribution on the machine that builds the container.

2. Create a Dockerfile that includes the Python source distribution. The ADD command automatically extracts the contents of the tar file into the target-dir directory:

   FROM opentext/vertica-k8s:version
   ADD lib-name.version.tar.gz /path/to/target-dir
   ...
   

   For a complete list of available database server images, see opentext/vertica-k8s Docker Hub repository.

3. Build the Dockerfile:

   $ docker build . -t image-name:tag
   

4. Push the image to a container registry so that you can add the image to a database custom resource:

   $ docker image push registry-host:port/registry-username/image-name:tag