clockworklabs / clockworklabs/SpacetimeDB

Support custom structs as primary keys

Open
#5,425 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

feature-request
Dominant language
Rust
Stars
25.2k
Forks
1.1k
Avg merge
2d 7h
Merged PRs (30d)
46

Description

Allow custom structs marked with [SpacetimeDB.Type] to be used as primary keys when they wrap a SpacetimeDB-supported primary-key type.

For example:

[SpacetimeDB.Type]
public partial struct ItemKey
{
    public ulong Value;

    public bool IsReserved()
    public ItemCategory GetItemCategory()

    public static implicit operator ulong(ItemKey key) => key.Value;
    public static implicit operator ItemKey(ulong value) =>
        new() { Value = value };
}

[SpacetimeDB.Table(Accessor = "Item", Public = true)]
public partial struct Item
{
    [SpacetimeDB.PrimaryKey]
    public ItemKey Key;

    public string Name;
}

Why?

Custom key types make it possible to attach arbitrary methods directly to a key.

This also could help prevent different kinds of keys from being mixed together accidentally, even when they use the same underlying type.

Without this support, the table field must use a built-in type, and the user has to repeatedly convert between that type and the custom struct before calling methods or passing the key to other parts of the application.

Proposed behavior

A struct marked with [SpacetimeDB.Type] should be usable as a primary key, unique key, or single-column index key when it wraps exactly one SpacetimeDB-supported primary-key type.

It would be acceptable to require implicit conversions and/or to and from the supported type. Alternatively, a dedicated attribute or other explicit way to identify the underlying key type would be reasonable.

SpacetimeDB could store and index the value using the supported underlying type, while generated APIs continue to use the custom struct.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by locating the C# handling for [SpacetimeDB.Type], [SpacetimeDB.PrimaryKey], unique keys, and single-column indexes, then trace the Rust implementation or code-generation entry points they use. Define how exactly one supported underlying key type is identified and represented. Done means custom structs such as ItemKey work for primary, unique, and single-column index keys while generated APIs continue to use the custom struct.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp, rust
Domain
databases
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.