Add TrailBase integration and example #228

ignatz · 2025-07-04T20:38:42Z

I've also started working on an example, as you suggested, but wanted to send out an RFC early.

Don't hold back. Let me know if this is going roughly the expected direction. If so, also let me know how you'd like to handle a potential example, e.g. should it be part of the same PR, should it be a full replica of the todo example?

Thanks!

changeset-bot · 2025-07-04T20:38:46Z

🦋 Changeset detected

Latest commit: fc889b1

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 7 packages

Name	Type
@tanstack/trailbase-db-collection	Patch
@tanstack/electric-db-collection	Patch
@tanstack/query-db-collection	Patch
@tanstack/db-example-react-todo	Patch
@tanstack/react-db	Patch
@tanstack/vue-db	Patch
@tanstack/db	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

KyleAMathews

Looking good!

BTW, thinking about this PR made me realize we really should have collection types be in their own packages so e.g. if you want to do a major release you can #235

We'll be migrating the other packages in the next day or two so you can just move this PR to create a new package.

packages/db-collections/src/trailbase.ts

ignatz · 2025-07-07T18:21:19Z

BTW, thinking about this PR made me realize we really should have collection types be in their own packages so e.g. if you want to do a major release you can #235

Sounds good. I was thinking the same, let alone when adding the backend-specific dependency.

We'll be migrating the other packages in the next day or two so you can just move this PR to create a new package.

If I understood correctly, we'll table this review until the split has happened for me to rebase? Sounds good, just ping this PR and I'll get the train rolling.

Did you think about the example, should we handle it in a follow-up?

Thanks!

KyleAMathews · 2025-07-14T17:31:27Z

The refactor is merged so you can now move your code to a trailbase-db-collection package #252

ignatz · 2025-07-14T17:54:07Z

Awesome! Moved to separate package.

KyleAMathews · 2025-07-14T17:57:56Z

Great! I also refactored the example so you can easily add a trail base version. Could you look at doing that? The docker backend perhaps could have a trail base setup too?

ignatz · 2025-07-14T18:05:57Z

Great! I also refactored the example so you can easily add a trail base version. Could you look at doing that? The docker backend perhaps could have a trail base setup too?

Sure can do. Quick questions:

Would you like me to add to the existing example?
If so, just add to the existing docker-compose or have a separate compose setup?
Would you like to make it part of this initial PR?

KyleAMathews · 2025-07-14T18:14:26Z

Yeah same example. It's meant to be an omnibus example so easily see every collection type. And yes, one command to start all of them. And yes in this pr as that'll make it easier to test.

ignatz · 2025-07-14T20:33:49Z

I added TrailBase to the example. I tried to fumble my way through...

Additions and deletions work, however update both for the config and todo fail due to zod validation. I have differnt data types. I already made created_at and updated_at strings, which worked for insertions but not for updates 🤷‍♀️

KyleAMathews · 2025-07-14T22:29:29Z

hmm interesting — you're using the zod schemas from drizzle it looks like? So you should use zod schemas consistent with the trailblaze schema? I suppose you can't have Date types w/ sqlite?

ignatz · 2025-07-15T07:25:35Z

hmm interesting — you're using the zod schemas from drizzle it looks like?

That my understanding, at first I tried to make mine compatible because I didn't necessarily want to change the downstream code.

So you should use zod schemas consistent with the trailblaze schema?

I guess so.

I suppose you can't have Date types w/ sqlite?

SQLite has a DATETIME type, which internally is just an INT64. That said, for type-safety reasons TrailBase requires STRICT mode (see migrations), which doesn't allow DATETIME. W/o STRICT, types are merely affinities and SQLite let's you stick any value into any column :)

KyleAMathews · 2025-07-15T17:38:55Z

Ok — yeah the other collections serialize & deserialize to/from Date objects — I imagine most people might want that for Trailblaze? Perhaps you could add a parser & serialize config option to the Trailblaze collection?

ignatz · 2025-07-15T17:59:05Z

Ok — yeah the other collections serialize & deserialize to/from Date objects — I imagine most people might want that for Trailblaze? Perhaps you could add a parser & serialize config option to the Trailblaze collection?

That's an interesting proposal. I would certainly love not to to diverge the downstream code of the example. Could you elaborate a bit how this could look like, is there any precedent for me to look at? Thanks

EDIT: Would this just be two functions:

parser: (record: Record) -> TItem,
serialize: (item: TItem) -. Record,

? If so, yeah, yeah I'll do that. It will certainly be a good starting point.

ignatz · 2025-07-15T19:37:23Z

Ok, I found

db/examples/react/todo/src/lib/collections.ts

Line 21 in b2ce3ed

timestamptz: (date: string) => new Date(date),

, which is probably what you meant. I'm not sure the same approach would work for me, since my base type is just INTEGER as opposed to PG TIMESTAMPZ.

Anyway, it works now 🎉 . Do you think this is a workable starting point?

KyleAMathews · 2025-07-15T20:15:27Z

Nice!

Yeah, parsing/serializing the whole row works — perhaps doing it per column would be better though as for big tables, it'd be tedious to have to pass through all the untouched stuff. Electric has a parser by pg type as you found.

KyleAMathews · 2025-07-16T01:06:38Z

I tested it briefly — update works if I refresh the page after adding a todo. But not if I add it and then try to check it off. Changing the color of the background doesn't work either.

ignatz · 2025-07-16T08:52:09Z

perhaps doing it per column would be better though as for big tables, it'd be tedious to have to pass through all the untouched stuff.

I like that, I'm just not sure my TS foo is strong enough. I'm aware that it can render Doom, but how would I define/infer a type Parse as follows:

type TItem = { 
 id: string;
 created: Date;
}
type TRecord = {
 id: string;
 created: number;
}

type Parse = {
 id?: (id: string) => string;
 created: (id: number) => Date;
}

function parse(parse: Parse, record: Partial<TRecord> | Record) : Partial<TItem> | TItem;

Instead I rewrote the serialize/parse implementations to only explicit set the relevant fields. Do you think this could be a workable starting point?

{
  parse: (record: Todo): SelectTodo => ({
    ...record,
    created_at: new Date(record.created_at * 1000),
    updated_at: new Date(record.updated_at * 1000),
  }),
}

I tested it briefly — update works if I refresh the page after adding a todo. But not if I add it and then try to check it off. Changing the color of the background doesn't work either.

My bad. Fixed

TrailBase-TanstackDB.mp4

…changing downstream example code.

KyleAMathews · 2025-07-16T12:40:56Z

No you have to test it in the same browser.

Screen.Recording.2025-07-16.at.6.39.01.AM.mp4

KyleAMathews · 2025-07-16T12:45:27Z

I'm not very good at types either which is why I ask Claude 😆 This is what it came up with:

// Parser type: takes input values and converts them to the target type
type Parser<T, InputType = unknown> = {
  [K in keyof T]?: (value: InputType) => T[K];
};

// Serializer type: takes the typed values and converts them to output format
type Serializer<T, OutputType = string> = {
  [K in keyof T]?: (value: T[K]) => OutputType;
};

ignatz · 2025-07-16T13:28:45Z

No you have to test it in the same browser.

Did you update and rebuild? I force-pushed an update that should fix your issue. In theory at least :hide:

KyleAMathews · 2025-07-16T13:46:44Z

ah oops! I ran git pull but I hadn't setup my checkout correctly and didn't notice I didn't get the latest changes.

It's all working now :-D

Let's get the parser/serializer slimmed down so you only specify what you actually want changed & then I think we're ready to go!

…records and vice-versa on the per-key level. One downside of this approach is that you always have to specify serialize/parse because I cannot be bothered to make them optional only if no conversions are needed.

ignatz · 2025-07-16T16:22:27Z

I'm not very good at types either which is why I ask Claude 😆 This is what it came up with:

// Parser type: takes input values and converts them to the target type
type Parser<T, InputType = unknown> = {
  [K in keyof T]?: (value: InputType) => T[K];
};

// Serializer type: takes the typed values and converts them to output format
type Serializer<T, OutputType = string> = {
  [K in keyof T]?: (value: T[K]) => OutputType;
};

I should have been more clear about knowing types well enough that I suspect that it's not trivial. No offense to Claude, would still love to meet them over a beverage and talk about their outlook on humanity 🙃

(There might be a simpler way but that's the easiest I could come up with)

I did do the gymnastics now. It's not pretty. They should be doing what you were asking for but now there's always a parse/serialize parameter needed. Otherwise the gymnastics get even worse. The more positive way to look at it is that previously it wasn't properly type-safe and now it is 🤷‍♀️

KyleAMathews · 2025-07-16T16:35:30Z

hmm why can't we make parse/serialize optional?

ignatz · 2025-07-16T16:37:40Z

Because they can only be optional when TItem and TRecord are fully compatible.

…

On Wed, 16 Jul 2025, 18:35 Kyle Mathews, ***@***.***> wrote: *KyleAMathews* left a comment (TanStack/db#228) <#228 (comment)> hmm why can't we make parse/serialize optional? — Reply to this email directly, view it on GitHub <#228 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAA3K4WJ6X6TTNRFATZJ7F33IZ5OTAVCNFSM6AAAAACA2DIAN6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTANZZGM4TOOJQG4> . You are receiving this because you authored the thread.Message ID: ***@***.***>

KyleAMathews · 2025-07-16T16:39:56Z

👍 works for me! Excited to get this out! Finishing up some other stuff but I'll get this merged and released a bit later today 🚀

ignatz · 2025-07-16T16:44:26Z

👍 works for me! Excited to get this out! Finishing up some other stuff but I'll get this merged and released a bit later today 🚀

Yay 🎉 - It was very fun working with you - looking forward to more.

PS: We can make parse/serialize conditionally optional in the future. It's just just more gymnastics but the change would be api backward compatible. As someone who mostly doesn't read docs, I'm just always happy when I can jump to definition and reasonably reason about the code.

KyleAMathews · 2025-07-16T16:49:08Z

It's just just more gymnastics

TypeScript always is haha.

It was fun working with you too! Hopefully TanStack/DB is a super nice addition for your community. I'll tweet it out too — are you / trailbase on the various socials?

ignatz · 2025-07-16T17:48:32Z

I can lookup my Twitter handle in a bit, I don't think I've ever used it 😇. Quick question, would you mind if I also update the example readme to clarify Migrations and point out the admin dash? Thanks again

…

On Wed, 16 Jul 2025, 18:49 Kyle Mathews, ***@***.***> wrote: *KyleAMathews* left a comment (TanStack/db#228) <#228 (comment)> It's just just more gymnastics TypeScript always is haha. It was fun working with you too! Hopefully TanStack/DB is a super nice addition for your community. I'll tweet it out too — are you / trailbase on the various socials? — Reply to this email directly, view it on GitHub <#228 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAA3K4R7H2RFH27TEK4E6HD3IZ7BVAVCNFSM6AAAAACA2DIAN6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTANZZGQZTIOJRGM> . You are receiving this because you authored the thread.Message ID: ***@***.***>

KyleAMathews · 2025-07-16T18:03:30Z

Yeah sure push away. Just lemme know when it's ready

ignatz · 2025-07-16T18:46:06Z

That turned out to be pretty minor 😅 . Feel free to change it as you see fit. All good from my side.

My pristine twitter handle is @trailbase_io (in case that's what you were asking for otherwise no need to mention 🤷‍♀️ ).

Last question, will you take care of publishing the npm package or would you rather have me do that? (not sure if there's some namespacing issue for the package)

Thanks again. This was fun, I'm very excited 🙏 🥳

- Fix Promise resolver implementation in test setup - Remove unnecessary async keywords from mock functions without await - Ensure proper Promise return types for mock implementations - Fix third test function to not be async when no await is used 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>

pkg-pr-new · 2025-07-16T19:35:18Z

@tanstack/db-example-react-todo

@tanstack/db

npm i https://pkg.pr.new/@tanstack/db@228

@tanstack/electric-db-collection

npm i https://pkg.pr.new/@tanstack/electric-db-collection@228

@tanstack/query-db-collection

npm i https://pkg.pr.new/@tanstack/query-db-collection@228

@tanstack/react-db

npm i https://pkg.pr.new/@tanstack/react-db@228

@tanstack/trailbase-db-collection

npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@228

@tanstack/vue-db

npm i https://pkg.pr.new/@tanstack/vue-db@228

commit: fc889b1

KyleAMathews · 2025-07-16T20:06:03Z

trailbase-demo.mp4

you need to rebuild your admin w/ db to get realtime updates 😆

KyleAMathews · 2025-07-16T20:15:15Z

https://x.com/kylemathews/status/1945577670550720583

ignatz · 2025-07-17T07:21:35Z

you need to rebuild your admin w/ db to get realtime updates 😆

You may be joking but the admin refresh does feel incredibly jarring 👀 😅

ignatz force-pushed the trailbase branch from 5bf28fa to c7bd2f8 Compare July 5, 2025 07:59

KyleAMathews reviewed Jul 7, 2025

View reviewed changes

packages/db-collections/src/trailbase.ts Outdated Show resolved Hide resolved

ignatz force-pushed the trailbase branch from c7bd2f8 to c04d359 Compare July 7, 2025 18:17

Add initial TrailBase integration and tests.

8690a58

ignatz force-pushed the trailbase branch from c04d359 to 8690a58 Compare July 14, 2025 17:53

Add TrailBase to the todo example.

db6a550

ignatz force-pushed the trailbase branch from ebd710f to f933216 Compare July 16, 2025 08:38

Add a parse/serialize translation layer to map JS Date objects w/o …

59bcb8d

…changing downstream example code.

ignatz force-pushed the trailbase branch from f933216 to 59bcb8d Compare July 16, 2025 09:12

minor: add mention of TrailBase admin UI to readme.

14ba457

KyleAMathews and others added 6 commits July 16, 2025 13:07

merge origin/main

8c33006

add new api markReady

36be0e3

use modified as that always has the full insert

49b9404

prettier

44adf42

add mention to README

6e1501f

KyleAMathews changed the title ~~Add initial TrailBase integration and tests.~~ Add TrailBase integration and tests. Jul 16, 2025

KyleAMathews changed the title ~~Add TrailBase integration and tests.~~ Add TrailBase integration and example Jul 16, 2025

KyleAMathews added 2 commits July 16, 2025 13:48

prettier

246b9c8

add changeset

fc889b1

KyleAMathews merged commit 09c6995 into TanStack:main Jul 16, 2025
4 of 5 checks passed

github-actions bot mentioned this pull request Jul 16, 2025

ci: Version Packages #273

Merged

Add TrailBase integration and example #228

Add TrailBase integration and example #228

Uh oh!

Conversation

ignatz commented Jul 4, 2025

Uh oh!

changeset-bot bot commented Jul 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

KyleAMathews left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ignatz commented Jul 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

KyleAMathews commented Jul 14, 2025

Uh oh!

ignatz commented Jul 14, 2025

Uh oh!

KyleAMathews commented Jul 14, 2025

Uh oh!

ignatz commented Jul 14, 2025

Uh oh!

KyleAMathews commented Jul 14, 2025

Uh oh!

ignatz commented Jul 14, 2025

Uh oh!

KyleAMathews commented Jul 14, 2025

Uh oh!

ignatz commented Jul 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

KyleAMathews commented Jul 15, 2025

Uh oh!

ignatz commented Jul 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ignatz commented Jul 15, 2025

Uh oh!

KyleAMathews commented Jul 15, 2025

Uh oh!

KyleAMathews commented Jul 16, 2025

Uh oh!

ignatz commented Jul 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

KyleAMathews commented Jul 16, 2025

Uh oh!

KyleAMathews commented Jul 16, 2025

Uh oh!

ignatz commented Jul 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

KyleAMathews commented Jul 16, 2025

Uh oh!

ignatz commented Jul 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

KyleAMathews commented Jul 16, 2025

Uh oh!

ignatz commented Jul 16, 2025 via email

Uh oh!

KyleAMathews commented Jul 16, 2025

Uh oh!

ignatz commented Jul 16, 2025

Uh oh!

KyleAMathews commented Jul 16, 2025

Uh oh!

ignatz commented Jul 16, 2025 via email

Uh oh!

KyleAMathews commented Jul 16, 2025

Uh oh!

ignatz commented Jul 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new bot commented Jul 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Jul 4, 2025 •

edited

Loading

ignatz commented Jul 7, 2025 •

edited

Loading

ignatz commented Jul 15, 2025 •

edited

Loading

ignatz commented Jul 15, 2025 •

edited

Loading

ignatz commented Jul 16, 2025 •

edited

Loading

ignatz commented Jul 16, 2025 •

edited

Loading

ignatz commented Jul 16, 2025 •

edited

Loading

ignatz commented Jul 16, 2025 •

edited

Loading

pkg-pr-new bot commented Jul 16, 2025 •

edited

Loading