databricks/zerobus-sdk-ts

databricks/zerobus-sdk-ts

Description: Zerobus SDK for TypeScript

Language: Rust

License: NOASSERTION

Stars: 5

Forks: 0

Open issues: 0

Created: 2025-11-19T14:12:40Z

Pushed: 2026-03-06T14:26:56Z

Default branch: main

Fork: no

Archived: yes

README: > This repository has been moved to [databricks/zerobus-sdk](https://github.com/databricks/zerobus-sdk/tree/main/typescript). This repo is archived and read-only. All new development, issues, and pull requests should go to the monorepo. > > | SDK | Link | > |-----|------| > | Rust | databricks/zerobus-sdk/rust | > | TypeScript | databricks/zerobus-sdk/typescript | > | Java | databricks/zerobus-sdk/java | > | Python | databricks/zerobus-sdk/python | > | Go | databricks/zerobus-sdk/go |

Databricks Zerobus Ingest SDK for TypeScript

GA: This SDK is generally available and supported for production use cases. Minor and patch version updates will not contain breaking changes. Major version updates may include breaking changes.

We are keen to hear feedback from you on this SDK. Please file issues, and we will address them.

The Databricks Zerobus Ingest SDK for TypeScript provides a high-performance client for ingesting data directly into Databricks Delta tables using the Zerobus streaming protocol. This SDK wraps the high-performance Rust SDK using native bindings for optimal performance.

Table of Contents

• [Features](#features)
• [Requirements](#requirements)
• [Quick Start User Guide](#quick-start-user-guide)
• [Prerequisites](#prerequisites)
• [Installation](#installation)
• [Choose Your Serialization Format](#choose-your-serialization-format)
• [Option 1: Using JSON (Quick Start)](#option-1-using-json-quick-start)
• [Option 2: Using Protocol Buffers (Default, Recommended)](#option-2-using-protocol-buffers-default-recommended)
• [Usage Examples](#usage-examples)
• [Authentication](#authentication)
• [Configuration](#configuration)
• [Descriptor Utilities](#descriptor-utilities)
• [Error Handling](#error-handling)
• [API Reference](#api-reference)
• [Best Practices](#best-practices)
• [Platform Support](#platform-support)
• [Architecture](#architecture)
• [Contributing](#contributing)
• [Related Projects](#related-projects)

Features

• High-throughput ingestion: Optimized for high-volume data ingestion with native Rust implementation
• Automatic recovery: Built-in retry and recovery mechanisms for transient failures
• Flexible configuration: Customizable stream behavior and timeouts
• Multiple serialization formats: Support for JSON and Protocol Buffers
• Type widening: Accept high-level types (plain objects, protobuf messages) or low-level types (strings, buffers) - automatically handles serialization
• Batch ingestion: Ingest multiple records with a single acknowledgment for higher throughput
• OAuth 2.0 authentication: Secure authentication with client credentials
• TypeScript support: Full type definitions for excellent IDE support
• Cross-platform: Supports Linux, macOS, and Windows

Requirements

Runtime Requirements

• Node.js: >= 16
• Databricks workspace with Zerobus access enabled

Build Requirements

• Rust toolchain: 1.70 or higher - Install Rust
• Cargo: Included with Rust

Dependencies

These will be installed automatically:

{
"@napi-rs/cli": "^2.18.4",
"napi-build": "^0.3.3"
}

Quick Start User Guide

Prerequisites

Before using the SDK, you'll need the following:

1. Workspace URL and Workspace ID

After logging into your Databricks workspace, look at the browser URL:

https://.cloud.databricks.com/?o=

• Workspace URL: The part before /?o= → https://.cloud.databricks.com
• Workspace ID: The part after ?o= → ``
• Zerobus Endpoint: https://.zerobus..cloud.databricks.com

> Note: The examples above show AWS endpoints (.cloud.databricks.com). For Azure deployments, the workspace URL will be https://.azuredatabricks.net and Zerobus endpoint will use .azuredatabricks.net.

Example:

• Full URL: https://dbc-a1b2c3d4-e5f6.cloud.databricks.com/?o=1234567890123456
• Workspace URL: https://dbc-a1b2c3d4-e5f6.cloud.databricks.com
• Workspace ID: 1234567890123456
• Zerobus Endpoint: https://1234567890123456.zerobus.us-west-2.cloud.databricks.com

2. Create a Delta Table

Create a table using Databricks SQL:

CREATE TABLE .default.air_quality (
device_name STRING,
temp INT,
humidity BIGINT
)
USING DELTA;

Replace ` with your catalog name (e.g., main`).

3. Create a Service Principal

1. Navigate to Settings > Identity and Access in your Databricks workspace 2. Click Service principals and create a new service principal 3. Generate a new secret for the service principal and save it securely 4. Grant the following permissions:

• USE_CATALOG on the catalog (e.g., main)
• USE_SCHEMA on the schema (e.g., default)
• MODIFY and SELECT on the table (e.g., air_quality)

Grant permissions using SQL:

-- Grant catalog permission
GRANT USE CATALOG ON CATALOG TO ``;

-- Grant schema permission
GRANT USE SCHEMA ON SCHEMA .default TO ``;

-- Grant table permissions
GRANT SELECT, MODIFY ON TABLE .default.air_quality TO ``;

Installation

Prerequisites

Before installing the SDK, ensure you have the required tools:

1. Node.js >= 16

Check if Node.js is installed:

node --version

If not installed, download from nodejs.org.

2. Rust Toolchain (1.70+)

The SDK requires Rust to compile the native addon. Install using rustup (the official Rust installer):

On Linux and macOS:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Follow the prompts (typically just press Enter to accept defaults).

On Windows:

Download and run the installer from rustup.rs, or use:

# Using winget…