Now that #25 is in, I'm having a crack at migrating an existing database (already manually upgraded to V3) over to surrealkit from surrealdb-migrations, but the actual process isn't clear to me.
There's a fair bit to cover here, so I'll split this into two parts:
SurrealKit itself
This is a fairly significant departure from what I expected. My expectation is essentially: define migrations, then run them.
But here, how do I actually write a migration? What does that conceptually map to?
What would help is some practical examples of using this tool, both from the perspective of a new DB, and of introducing changes to an existing one. This is a fairly novel approach to database management, so it could really do with an explanation of what these concepts specifically do.
https://discord.com/channels/902568124350599239/1492233799164235987/1492234656383500470 suggests syncs are "just create and delete", but as far as I'm aware that isn't actually documented anywhere.
The library implementation
Firstly, thanks for putting this in!
The library documentation suggests this is something I do via rollouts: https://github.com/surrealdb/surrealkit/blob/main/crates/surrealkit/README.md, is that right?
EmbeddedSchemaFile also stands out, why does it have both a path and schema field? Why do we have two copies of the SQL here? RolloutSpec's SQL field is identical to the above.
RolloutStep would benefit from comments. Reading it now, I have the same question for files, expect, and entities, what do these do in practice?
RolloutSpec raises similar questions. What do these fields do? What are the implications? What decisions do I make?
compatibility feels like it should be an enum, judging by the name it sounds like it has a finite set of options.
For idempotents, it'd be useful to explain what None does.
Inline SQL (step.sql) and file references (step.files) are mutually exclusive within one step. Use one or the other.
In this case the types should enforce that, and an explanation of why would also be useful.
Only one rollout can be active at a time. run_start_with_spec returns an error if a different rollout is already in the running_start or ready_to_complete state.
This feels like a footgun, how do I recover from it?
I think the pattern's pretty clear by now.
Being different isn't inherently a problem, but when deviating from convention, more care than usual is needed to explain how it's different and why. So if it's at all possible, I'd recommend borrowing a team member for an hour or two to walk through using this in practice.
Now that #25 is in, I'm having a crack at migrating an existing database (already manually upgraded to V3) over to
surrealkitfromsurrealdb-migrations, but the actual process isn't clear to me.There's a fair bit to cover here, so I'll split this into two parts:
SurrealKit itself
This is a fairly significant departure from what I expected. My expectation is essentially: define migrations, then run them.
But here, how do I actually write a migration? What does that conceptually map to?
What would help is some practical examples of using this tool, both from the perspective of a new DB, and of introducing changes to an existing one. This is a fairly novel approach to database management, so it could really do with an explanation of what these concepts specifically do.
https://discord.com/channels/902568124350599239/1492233799164235987/1492234656383500470 suggests syncs are "just create and delete", but as far as I'm aware that isn't actually documented anywhere.
The library implementation
Firstly, thanks for putting this in!
The library documentation suggests this is something I do via rollouts: https://github.com/surrealdb/surrealkit/blob/main/crates/surrealkit/README.md, is that right?
EmbeddedSchemaFilealso stands out, why does it have both apathandschemafield? Why do we have two copies of the SQL here?RolloutSpec's SQL field is identical to the above.RolloutStepwould benefit from comments. Reading it now, I have the same question forfiles,expect, andentities, what do these do in practice?RolloutSpecraises similar questions. What do these fields do? What are the implications? What decisions do I make?compatibilityfeels like it should be an enum, judging by the name it sounds like it has a finite set of options.For
idempotents, it'd be useful to explain whatNonedoes.In this case the types should enforce that, and an explanation of why would also be useful.
This feels like a footgun, how do I recover from it?
I think the pattern's pretty clear by now.
Being different isn't inherently a problem, but when deviating from convention, more care than usual is needed to explain how it's different and why. So if it's at all possible, I'd recommend borrowing a team member for an hour or two to walk through using this in practice.