cupug

Getting Started

cupug is a PostgreSQL extension. You write standard SQL, and the GPU accelerates query execution transparently. No special query syntax, no separate query engine, no data migration to a proprietary format.

Prerequisites

• PostgreSQL 16 or 17
• NVIDIA GPU with CUDA 12.4+
• cupug installed (see Build and Test)

Creating the Extension

Connect to your database and create the extension:

CREATE EXTENSION cupug;

Verify it registered its access method:

SELECT amname FROM pg_am WHERE amname = 'cupug_tam';

If this returns a row, cupug is ready.

Creating Tables

cupug provides two storage layouts. Both are created through standard CREATE TABLE with the USING clause.

Heap Block Storage

CREATE TABLE events (
    id       bigint GENERATED ALWAYS AS IDENTITY,
    ts       timestamptz NOT NULL,
    user_id  bigint NOT NULL,
    action   text,
    payload  jsonb
) USING cupug_tam;

Heap block storage is compatible with all existing PostgreSQL features including indexes, TOAST, and foreign keys. It is a good default for mixed read/write workloads.

To migrate an existing table to cupug:

CREATE TABLE events_gpu USING cupug_tam AS SELECT * FROM events;

Column Block Storage

CREATE TABLE events (
    id       bigint GENERATED ALWAYS AS IDENTITY,
    ts       timestamptz NOT NULL,
    user_id  bigint NOT NULL,
    action   text,
    payload  jsonb
) USING cupug_tam WITH (storage = 'columnar');

Column block storage is optimized for analytics. Only the columns referenced by a query are read from storage, and the GPU decompresses data in parallel using nvCOMP.

Storage Options

Option	Values	Default	Description
storage	heap, columnar	heap	Physical layout of the table on disk
compression	none, lz4, zstd	none	Compression codec for columnar storage

Example with compression:

CREATE TABLE events (
    id       bigint GENERATED ALWAYS AS IDENTITY,
    ts       timestamptz NOT NULL,
    user_id  bigint NOT NULL,
    action   text,
    payload  jsonb
) USING cupug_tam WITH (storage = 'columnar', compression = 'lz4');

Loading Data

For bulk loads, use COPY:

COPY events FROM '/path/to/events.csv' WITH (FORMAT csv, HEADER);

To migrate data from another table:

INSERT INTO events SELECT * FROM legacy_events;

Your First Query

Once data is loaded, run a standard aggregate:

SELECT
    date_trunc('hour', ts) AS hour,
    count(*)               AS event_count,
    count(DISTINCT user_id) AS unique_users
FROM events
WHERE ts >= now() - interval '7 days'
GROUP BY 1
ORDER BY 1;

This is ordinary PostgreSQL SQL. cupug executes the scan, filter, and aggregation on the GPU automatically.

Default Access Method

If most of your tables will use cupug, set it as the default so you can omit the USING clause:

SET default_table_access_method = 'cupug_tam';

To make this permanent, add it to postgresql.conf:

default_table_access_method = 'cupug_tam'