Build with PacificDB.

START HERE

Install PacificDB

The native packages include the database engine and native CLI. Choose the package matching your operating system and processor.

Linux: Ubuntu and Debian

Download the x86-64 .deb from the v1.1.2 prerelease, then install it with APT.

sudo apt install ./pacificdb-community-1.1.2-linux-amd64.deb
pacificdb --version
pacificdb

Windows

Install Windows Workbench 1.1.2 for the desktop app with its bundled engine and CLI. A standalone v1.1.2 engine installer has not been published.

macOS

Final v1.1.2 installers are not published; signing/notarization and platform qualification remain pending.

npm CLI and Node.js client

Node.js 18 or newer is required. Install both verified GitHub tarballs together. npm registry 1.1.2 publication remains pending.

npm install --global https://github.com/hitesh-reddy-k/pacificdb-community/releases/download/1.1.2/pacificdb-client-1.1.2.tgz \
  https://github.com/hitesh-reddy-k/pacificdb-community/releases/download/1.1.2/pacificdb-cli-1.1.2.tgz
npm install https://github.com/hitesh-reddy-k/pacificdb-community/releases/download/1.1.2/pacificdb-client-1.1.2.tgz

The npm CLI is a client; installing it does not install the engine.

Docker from the release checkout

docker compose up -d --build database
docker compose run --rm shell

Data remains in the pacificdb-data volume.

Build v1.1.2 from source

Check out immutable tag 1.1.2 (displayed version v1.1.2). Requirements: CMake 3.20+, C++17 compiler, OpenSSL development headers, LZ4, RE2, and Node.js 22.12+ for Workbench development. On Debian/Ubuntu, install libssl-dev, liblz4-dev and libre2-dev before configuring.

git checkout 1.1.2
cmake -S engine -B build -DCMAKE_BUILD_TYPE=Release -DPACIFICDB_ENGINE_VERSION=1.1.2
cmake --build build -j2
./build/pacificdb

FIRST DOCUMENT

Quickstart

Install 1.1.2 and run pacificdb. On a loopback connection, the native CLI starts the local engine automatically when it is not already running, then opens the shell.

create database hello
create collection ideas
insert ideas {"id":"first","title":"Hello PacificDB"}
find ideas {"id":"first"}

Creating a database selects it automatically in the 1.1.2 CLI.

CONNECT DIRECTLY

Database URLs and authentication

pacificdb://127.0.0.1:9000/app addresses the database protocol. It is not a website and does not open in a browser. Workbench browser mode prints a separate http://127.0.0.1:PORT/ address. Use pacificdbs:// for TLS with certificate and hostname verification.

A URL selects its database; it does not create it. Creation selects the new database after success. No project selection is required. Omit create calls for existing databases and collections; they are not idempotent.

pacificdb --url 'pacificdb://127.0.0.1:9000/app' --no-start

For an authenticated server, set PACIFICDB_URL privately to your complete URL with an encoded username and password, then use the environment variable in each example. Both credentials are required. Do not paste private URLs in source, shared commands, or logs. The native CLI and npm Workbench read this variable. Local desktop mode uses its own loopback engine without an external account.

The 1.1.2 SDKs accept userId, timeoutMs, poolSize, and caFile URL query options. Pool size is 1–32; default is 16. Python explicit options use user_id, timeout (seconds), pool_size, ca_file. Java/Node use userId, timeoutMs, poolSize, caFile. Unknown/duplicate options and conflicting URL/CLI flags fail before connecting.

COMPATIBILITY

Legacy project APIs

Projects remain optional stored metadata. Existing mappings and data are preserved. The new CLI and Workbench use databases directly; their friendly project commands and screens are removed. Legacy SDK createProject/useProject and raw community_project_* APIs remain available for existing consumers.

STRUCTURE

Databases and collections

Create a database to select it automatically, then create a collection. Use an existing database with use <name> or a database-specific connection URL.

READ AND WRITE

Documents and queries

Document commands accept JSON objects directly in the shell.

create collection users
insert users {"id":"1","name":"Ada","active":true}
find users {"active":true}
findOne users {"id":"1"}
update users {"id":"1"} {"name":"Ada Lovelace"}
count users {"active":true}
delete users {"id":"1"}

Bounded aggregation

The Community aggregation pipeline supports $match, inclusion $project, sort, $skip, $limit, and terminal $count.

aggregate users [{"$match":{"active":true}},{"$project":{"name":1}},{"$sort":{"name":1}},{"$limit":10}]
explain users {"id":"1"}

REFERENCE

Shell command reference

The native and npm shells use the same friendly command names and engine actions. Run quit or exit to close the shell; its background engine keeps running. Run help for the installed version’s command list.

npm shell

Connect the installed 1.1.2 shell to an existing engine:

pacificdb --url 'pacificdb://127.0.0.1:9000/app' --no-start

create database <name>
list databases
use <name>
show database
drop database <name>
create collection <name>
list collections
insert <collection> <json>
find <collection> [filter-json]
findOne <collection> [filter-json]
update <collection> <filter> <json>
delete <collection> <filter-json>
aggregate <collection> <pipeline>
count <collection> [filter-json]
explain <collection> [filter-json]

create backup [--name <name>]
list backups
show backup <id>
restore backup <id>
list restores
delete backup <id>
backup verify <id>
backup export <id> [file]

create api-key [--name <n>] [--role read|readwrite|admin]
list api-keys
show api-key <id>
revoke api-key <id>

upload image|video|media <path> [--collection <name>] [--resume <id>]
download media <id> <path>
list media [--all]
find media <query>
show media <id>
delete media <id>
media cleanup <id>

put vector <collection> <id> <json-vector>
query vector <collection> <json-vector> [--k <n>] [--metric <name>]

help [topic]
context show
context clear
status
history
clear
request <json>
exit | quit

NODE.JS SDK

Node.js

The Apache-2.0 client requires Node.js 18+. Install the exact release:

npm install https://github.com/hitesh-reddy-k/pacificdb-community/releases/download/1.1.2/pacificdb-client-1.1.2.tgz

Start the 1.1.2 engine once with pacificdb. Save the following as hello.mjs and run node hello.mjs.

Use a fresh example database or omit creation for existing data. The file examples require a nonempty demo.mp4 in the current directory and an existing destination directory. Vector collections in these examples use two finite numeric dimensions. Authentication follows the private connection URL guide.

import { PacificDB } from '@pacificdb/client';

const url = process.env.PACIFICDB_URL ?? 'pacificdb://127.0.0.1:9000/node_demo';
const db = await PacificDB.connect(url);
try {
  await db.createDatabase(); // Create the URL database; omit if it exists.
  await db.createCollection('users');
  await db.insert('users', { id: '1', name: 'Ada' });
  console.log(await db.find('users', { id: '1' }, { limit: 1 }));
  await db.updateOne('users', { id: '1' }, { $set: { name: 'Grace' } });
  console.log(await db.request({ action: 'count', collection: 'users', filter: {} }));
  await db.deleteOne('users', { id: '1' });

  await db.createCollection('embeddings');
  await db.putVector('embeddings', 'v1', [0.2, 0.8], { kind: 'vector' });
  console.log(await db.queryVector('embeddings', [0.2, 0.8], { k: 5, metric: 'cosine' }));

  await db.createCollection('assets');
  const media = await db.uploadMediaFile('assets', './demo.mp4');
  await db.downloadMediaFile(media.id, './downloaded-node.mp4');
} finally {
  db.close();
}

For direct authentication use await db.authenticate(username, password); a private URL authenticates on connect. insertMany sends a batch. Use request({ action: 'aggregate', collection, pipeline }) or request({ action: 'explain', collection, filter }) for aggregation and explain. The Node.js SDK exposes these through raw protocol requests. Always call close() in a finally block.

PYTHON SDK

Python

Requires Python 3.10+ and has no runtime dependencies. PyPI trusted-publisher registration is still pending, so install the verified v1.1.2 wheel in a virtual environment:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --no-deps \
  'https://github.com/hitesh-reddy-k/pacificdb-community/releases/download/1.1.2/pacificdb-1.1.2-py3-none-any.whl'

Start the 1.1.2 engine, save as hello.py, then run python hello.py.

Use a fresh example database or omit creation for existing data. The file examples require a nonempty demo.mp4 in the current directory and an existing destination directory. Vector collections in these examples use two finite numeric dimensions. Authentication follows the private connection URL guide.

import os
from pathlib import Path
from pacificdb import PacificDB

url = os.environ.get('PACIFICDB_URL', 'pacificdb://127.0.0.1:9000/python_demo')
with PacificDB.connect(url) as db:
    db.create_database()  # Omit for an existing database.
    db.create_collection('users')
    db.insert('users', {'id': '1', 'name': 'Ada'})
    print(db.find_one('users', {'id': '1'}))
    db.update_one('users', {'id': '1'}, {'$set': {'name': 'Grace'}})
    print(db.count('users'))
    db.delete_one('users', {'id': '1'})

    db.create_collection('embeddings')
    db.vectors.insert(collection='embeddings', data={'id': 'v1', 'kind': 'vector', 'vector': [0.2, 0.8]})
    print(db.vectors.query(collection='embeddings', vector=[0.2, 0.8], k=5, metric='cosine'))

    db.create_collection('assets')
    media = db.media.upload_file('assets', Path('demo.mp4'))
    db.media.download_file(media['id'], Path('downloaded-python.mp4'), collection='assets')
# The context manager closes pooled connections, including on failure.

Direct authentication is db.authenticate(username, password). An API key can be installed with db.security.use_token(key). Advanced named families include indexes, vectors, media, backups, security, and admin. Their fields follow the engine protocol. PacificDBError.code identifies typed errors. Use with or explicitly call close().

JAVA SDK

Java

Requires Java 11+ and Maven; Jackson is the runtime dependency. Coordinates are io.pacificdb:pacificdb-client:1.1.2. Maven Central publication remains unavailable. This tag includes the reviewed Jackson 2.18.11 dependency; install its source into your local Maven repository:

git checkout 1.1.2
mvn -f sdk/java/pom.xml install

Add this dependency to an application with Maven compiler release 11 or newer. It resolves the locally installed 1.1.2 package.

<dependency>
  <groupId>io.pacificdb</groupId>
  <artifactId>pacificdb-client</artifactId>
  <version>1.1.2</version>
</dependency>

Start the 1.1.2 engine and place Hello.java below in src/main/java of that application.

Use a fresh example database or omit creation for existing data. The file examples require a nonempty demo.mp4 in the current directory and an existing destination directory. Vector collections in these examples use two finite numeric dimensions. Authentication follows the private connection URL guide.

import io.pacificdb.PacificDB;
import java.nio.file.Path;
import java.util.List;
import java.util.Map;

public class Hello {
    public static void main(String[] args) {
        String url = System.getenv().getOrDefault("PACIFICDB_URL", "pacificdb://127.0.0.1:9000/java_demo");
        try (var db = PacificDB.connect(url)) {
            db.createDatabase(); // Omit for an existing database.
            db.createCollection("users");
            db.insert("users", Map.of("id", "1", "name", "Ada"));
            System.out.println(db.findOne("users", Map.of("id", "1")));
            db.updateOne("users", Map.of("id", "1"), Map.of("$set", Map.of("name", "Grace")));
            System.out.println(db.count("users"));
            db.deleteOne("users", Map.of("id", "1"));

            db.createCollection("embeddings");
            db.vectors().insert(Map.of("collection", "embeddings", "data",
                Map.of("id", "v1", "kind", "vector", "vector", List.of(0.2, 0.8))));
            System.out.println(db.vectors().query(Map.of("collection", "embeddings",
                "vector", List.of(0.2, 0.8), "k", 5, "metric", "cosine")));

            db.createCollection("assets");
            var media = db.media().uploadFile("assets", Path.of("demo.mp4"));
            db.media().downloadFile((String)media.get("id"), Path.of("downloaded-java.mp4"), "assets");
        } // AutoCloseable closes the pool, including on failure.
    }
}

mvn package dependency:build-classpath -Dmdep.outputFile=classpath.txt
java -cp "target/classes:$(cat classpath.txt)" Hello

On Windows use a semicolon between classpath entries. Direct authentication is db.authenticate(username, password); API keys use db.security().useToken(key). Advanced operations take a Map of exact engine fields. PacificDBException.getCode() exposes typed errors. Use try-with-resources or explicitly call close().

DATA OPERATIONS

Backups and restore

Replace backup_... with the created backup ID. Run restore examples only on isolated test data; restore changes server data.

Community backups are operator-triggered full snapshots. Restore runs synchronously and records completed and failed attempts.

create backup --name before-upgrade
list backups
show backup backup_...
backup verify backup_...
backup export backup_... ./before-upgrade.json
restore backup backup_...
list restores
delete backup backup_...

DATA OPERATIONS

API keys

Keys can use the read, readwrite, or admin role. Creation and revocation require an administrator.

create api-key --name application --role readwrite
list api-keys
show api-key key_...
revoke api-key key_...

DATA OPERATIONS

Media files

Images, GIFs, audio, video, and arbitrary files transfer sequentially in bounded Base64-safe chunks. Every chunk and completed file is verified with SHA-256.

create collection videos
upload video ./demo.mp4 --collection videos
list media
show media media_...
download media media_... ./downloaded.mp4

Replace media_... with the upload’s returned ID. For an interrupted upload, resume the same unchanged file and collection with upload video ./demo.mp4 --collection videos --resume media_.... Use media cleanup media_... only to discard an incomplete upload. PacificDB applies no application-level total file-size cap. Available disk space, request limits, network time, and machine resources still limit transfers.

DATA OPERATIONS

Vector search

Vectors must be non-empty arrays of finite numbers. Query k must be a positive integer. Supported metrics include cosine, L2/euclidean, dot, and dot product.

create collection embeddings
put vector embeddings item-1 [0.2,0.8]
put vector embeddings item-2 [0.8,0.2]
query vector embeddings [0.2,0.8] --k 5 --metric cosine

Node.js vector API

await db.putVector('embeddings', 'hero-vector', [0.2, 0.8], {
  modality: 'image', assetId: 'hero'
});
const matches = await db.queryVector('embeddings', [0.2, 0.8], {
  k: 5, filter: { assetId: 'hero' }
});

DESKTOP AND BROWSER

Workbench

Workbench 1.1.2 includes the engine, CLI, and runtime. Linux Debian/portable packages are in the Community prerelease; the Windows x64 installer is in the Windows unsigned prerelease.

Windows x64 (unsigned prerelease)

This tested installer is unsigned. Windows may show an unknown-publisher or SmartScreen warning; follow your device or organization’s installation policy.

1. Download PacificDB-Workbench-1.1.2-win-x64.exe and its SHA256SUMS.
2. Run Get-FileHash .\PacificDB-Workbench-1.1.2-win-x64.exe -Algorithm SHA256 in PowerShell and compare the result with the installer's entry in that manifest.
3. Open the installer, complete its steps, then launch PacificDB Workbench from the Start menu. No separate engine or Node.js installation is required.

Quit Workbench before upgrading. Uninstall through Windows Installed apps; the database directory is retained at %APPDATA%\PacificDB Workbench\database. Verify a backup before upgrading or removing data.

Linux

Download the Debian installer and the Community release's SHA256SUMS to the same directory:

sha256sum --check --ignore-missing SHA256SUMS
sudo apt install ./PacificDB-Workbench-1.1.2-linux-amd64.deb
pacificdb-workbench

Workbench lists databases directly, preserves existing metadata, copies database URLs and SDK examples, and bounds Overview count work. See the update notes.

Run from source

Build the native engine as shown above, then:

npm ci
npm run workbench:desktop

On Linux, when Electron reports incorrect SUID sandbox helper configuration, set ownership and mode on your local helper:

sudo chown root:root node_modules/electron/dist/chrome-sandbox
sudo chmod 4755 node_modules/electron/dist/chrome-sandbox
npm run workbench:desktop

The Debian package’s desktop/after-install.sh sets root ownership and mode 4755 on /opt/PacificDB Workbench/chrome-sandbox, registers /usr/bin/pacificdb-workbench, and refreshes the desktop database. The application and database engine run as your normal user.

Optional browser mode

PATH="$PWD/build:$PATH" npm run workbench -- --ui-port 3001

Open the printed http://127.0.0.1:3001/ address; keep the terminal open. This differs from the engine’s pacificdb:// URL. --port selects the engine port and --ui-port the web port. The native CLI does not provide the npm workbench subcommand.

Documents, vectors, media and closing

Create/select a database and collection. Documents supports insert, JSON filters, edit and confirmed delete; Vectors accepts numeric embeddings and cosine/L2/dot queries. Media uploads are limited to 64 MiB in this UI; use SDK file transfers for larger files. “Local engine” copies the selected database URL, CLI command or SDK example without credentials. Quit desktop Workbench to close its engine; browser Ctrl+C closes the UI server while an automatically started engine keeps running.

Desktop data normally lives in ~/.config/PacificDB Workbench/database, separate from CLI data. Use File → Open data folder and File → Copy CLI connection command to reach the same running engine. Its port can change at the next launch.

OPERATE

Configuration and local files

Connect to another engine

pacificdb --host db.example.internal --port 9000 --no-start
pacificdb --host db.example.internal --port 9000 ping --no-start

Engine home

OPERATE

Security checklist

• Keep development mode bound to 127.0.0.1.
• Enable authentication and TLS before accepting network connections.
• Give applications the smallest API-key role they need.
• Store passwords and API keys outside source code and logs.
• Restrict filesystem access to PacificDB data and backup roots.
• Verify backups and perform restoration drills on isolated data roots.

OPERATE

Troubleshooting

SDK import/method errors usually mean an older package is installed: reinstall version 1.1.2 in your environment or local Maven repository. For connection refused, start the engine and verify its current host/port. For TLS failures check the server hostname and trust chain; supply a valid custom CA rather than disabling verification. After a failed write, inspect server state before retrying. For media errors keep the upload ID and same file for explicit resume; check disk space and destination permissions.

A pacificdb:// URL cannot be opened as a browser page. Use Workbench’s printed HTTP URL. For the Linux sandbox error follow the helper setup; a Debian install runs the configured after-install hook.

EXISTING INSTALLATIONS

Upgrade to v1.1.2

Keep the existing binaries and verify a full backup before upgrading. Stop applications and the matching engine before replacing binaries; test against a copy of your data in an isolated data directory. Install the matching 1.1.2 engine and SDK packages, then confirm pacificdb --version.

v1.1.2 requires explicit superadmin assignment for legacy authenticated databases without owners, a review of grants, and RE2-compatible regex filters. Backreferences/lookarounds are rejected. See the security upgrade notes.

The database-first workflow preserves project metadata: project mappings remain stored and legacy SDK/raw APIs remain available. A created database becomes selected automatically; use a database URL or use name for existing data. Friendly project CLI commands and Workbench project screens are removed. Older CLI context retains its database and clears project IDs/tokens.

Use matching 1.1.2 SDKs for URL/CRUD/file convenience methods, close pooled connections, and catch typed errors. Interrupted writes can have an unknown outcome and are never automatically retried. Resume media explicitly using the returned upload ID and unchanged source file. Verify downloads before restoring/replacing any destination file.

OPERATE

v1.1.2 status and support

Version 1.1.2 is the current Community prerelease, not certified production-ready. Verify checksums for native and Workbench downloads and report installation or compatibility problems through the issue tracker.