TypeDB Development

This repository orchestrates development across all TypeDB repositories using git submodules.

Setup

# Clone the repository
git clone git@github.com:typedb/typedb-dev.git
cd typedb-dev

# Initialize submodules and configure remotes
tool/repo init

# Or initialize only specific repos (e.g., if you don't have access to private repos)
tool/repo init typedb typeql typedb-driver

The init command will:

1. Initialize git submodules
2. Rename origin remote to typedb (upstream)
3. Add your GitHub fork as a remote named after your username

Your GitHub username is detected via gh CLI or git config github.user.

Quick Start

# Check status of all repositories
tool/repo status

# Start working on a feature across multiple repos
tool/repo checkout my-feature typedb typeql typedb-driver

# Switch to an existing remote feature branch
tool/repo switch existing-feature typedb typeql

# Reset repos back to master when done
tool/repo reset typedb typeql typedb-driver

# Fetch latest from all repos
tool/repo fetch

Repository Structure

typedb-dev/
├── tool/
│   ├── repo                    # Multi-repo management script
│   └── setup-docker-sandbox    # Docker sandbox for Claude Code
├── .claude/
│   └── commands/               # Custom slash commands
├── CLAUDE.md                   # AI agent instructions
├── architecture.md             # Technical documentation
│
└── repositories/
    ├── typedb/            # Core database server (Rust)
    ├── typedb-driver/     # Multi-language client drivers
    ├── typeql/            # Query language parser
    ├── typedb-protocol/   # gRPC protocol definitions
    ├── typedb-console/    # Interactive CLI client
    ├── typedb-studio/     # GUI desktop application
    ├── typedb-cluster/    # Clustered TypeDB (private)
    ├── typedb-cloud/      # Cloud platform (private)
    ├── dependencies/      # Shared Bazel build config
    ├── bazel-distribution/ # Package deployment rules
    ├── typedb-behaviour/  # BDD test specifications
    ├── typedb-docs/       # Documentation site
    └── typedb-examples/   # Example projects

Repository Tool

The tool/repo script manages submodules and branches.

Command	Description
init [repos...]	Initialize submodules, configure remotes, and add user's fork
checkout <feature> <repos...>	Create/checkout feature branch in specified repos
switch <feature> <repos...>	Switch to existing feature branch (fetches from remote)
status [--feature <name>]	Show status of all repos
commit <feature> "<message>"	Commit changes in all repos on the feature branch
push <fork> <feature>	Push feature branch to fork and show PR links
reset <repos...>	Reset repos back to master
fetch [repos...]	Fetch from remote (all repos if none specified)
list	List all available repos

Note: The commit and push commands only operate on submodule repositories. The meta-repository should be committed/pushed manually.

Sandboxed Development

For isolated development where Claude Code can operate with full permissions, use the Docker sandbox:

# Create a Docker sandbox
tool/setup-docker-sandbox myproject ghp_xxxx --shared-dir /path/to/project

# Attach to existing sandbox
tool/setup-docker-sandbox myproject --attach

# List running sandboxes
tool/setup-docker-sandbox --list

# Remove a sandbox
tool/setup-docker-sandbox myproject --remove

The Docker sandbox:

• Creates an isolated Ubuntu container
• Mounts only the specified project directory
• Runs as a non-root user
• Installs Claude Code automatically

Security: Requires a fine-grained GitHub token with minimal permissions:

• Limited to only necessary repositories
• Read/Write Contents and Pull Requests only
• Short expiration (7-30 days recommended)
• Create pre-configured token

Dependency Graph

                    ┌─────────────────┐
                    │  dependencies   │
                    └────────┬────────┘
                             │
    ┌────────────────────────┼────────────────────────┐
    ▼                        ▼                        ▼
┌──────────────────┐    ┌─────────┐    ┌──────────────────┐
│bazel-distribution│    │ typeql  │    │ typedb-behaviour │
└──────────────────┘    └────┬────┘    └────────┬─────────┘
                             │                  │
┌────────────────┐           │                  │
│ typedb-protocol│           │                  │
└───────┬────────┘           │                  │
        │                    │                  │
        ├────────────────────┼──────────────────┤
        ▼                    ▼                  ▼
┌──────────────┐        ┌──────────┐    ┌──────────────┐
│ typedb-driver│        │  typedb  │    │typedb-console│
└──────┬───────┘        └────┬─────┘    └──────────────┘
       │                     │
       │                     ▼
       │              ┌──────────────┐
       │              │typedb-cluster│
       │              └──────────────┘
       ▼
┌─────────────┐
│ typedb-cloud│
└─────────────┘

Local Development with Bazel Overrides

When developing across multiple repos, override Bazel's git dependencies to use local paths:

Modify dependencies/typedb/repositories.bzl:

# Before (fetches from git)
def typeql():
    git_repository(
        name = "typeql",
        remote = "https://github.com/typedb/typeql",
        tag = "3.7.0",
    )

# After (uses local path)
def typeql():
    native.local_repository(
        name = "typeql",
        path = "../typeql"
    )

Or use command-line overrides:

bazel build //target \
  --override_repository=typeql=$(pwd)/../typeql \
  --override_repository=typedb_protocol=$(pwd)/../typedb-protocol

Git Configuration

• Remote name: typedb (not origin)
• Default branch: master
• Merge strategy: Squash, then rebase before merging PRs

PR Merge Order

When changes span repos, merge PRs in dependency order:

1. dependencies / bazel-distribution
2. typedb-behaviour
3. typeql
4. typedb-protocol
5. typedb
6. typedb-cluster
7. typedb-driver
8. typedb-console / typedb-studio
9. typedb-cloud

Documentation

• CLAUDE.md - Detailed development guidelines and code conventions
• architecture.md - Technical documentation for the orchestration system