Convex Ents documentation: code comment // You can now use ctx.table as well:
In this messages.ts code example
https://labs.convex.dev/convex-ents/setup/existing#setup-custom-functions
There is a code comment that says
// You can now use ctx.table as well:
Is that "as well" statement actually true? My interpretation of the Convex Ents docs is that using Convex Ents is an all-or-nothing commitment:
- The developer totally replaces defineEntSchema() with defineSchema(), and doesn't use defineSchema() at all for the foreseeable future
- A project that uses Convex Ents does not use this import statement at all:
import { mutation, query } from "./_generated/server";
And so should not be using ctx.db.query()
Is this interpretation correct?
Setup Ents in an existing Convex project - Convex Ents
Relations, default values, unique fields and more for Convex
8 Replies
Here is a corresponding #ask-ai post that started this question:
https://discord.com/channels/1019350475847499849/1266038374867796029
Separate note: It'd be helpful to have more guidance on the implications of choosing to use Convex Ents.
I have a chance before asking people to use my app to transition to Convex Ents. I wonder if I will lose the benefits of future enhancement to Vanilla Convex.
I also don't have a great sense of the Venn Diagram of functionality between Convex Ents and convex-helper library
To talk about schema specifically, I believe any vanilla convex schema should be compatible with ents (e.g. you can replace
defineTable with defineEnt, and all your existing code using ctx.db will Just Work).
So I think it would be feasible to keep a lot of your existing table definitions + keep using ctx.db, and then use the ent features like edges, uniqueness, cascading deletes etc. for new tables or slowly transition your existing tables to use edges + ctx.table.
I believe the docs recommend setting up custom functions with both ctx.db + ctx.table at first, and then an optional step to move fully to using ctx.table (https://labs.convex.dev/convex-ents/setup/existing#optional-finish-moving-to-ctxtable)
(take all of this with a grain of salt, I'm mostly going off a previous hack day a while ago where I moved one of my projects to use ents)Setup Ents in an existing Convex project - Convex Ents
Relations, default values, unique fields and more for Convex
Okay, thanks Sarah. I got confused by the Ents docs because the code diff showed that this line of code was deleted:
- import { mutation, query } from "./_generated/server";
So, I assumed that the developer should not be using ctx.db.query()
But zooming out, I recognize that a vanilla Convex schema is compatible today, but the important question is: what are the implications for the future? i.e. Am I going to miss out on future vanilla Convex features if I commit to Convex Ents today
I've used ctx.db and ctx.table at the same time
The <Pick allows you to scope
db for certain tables only, but if you don't, messages will show up / be usable in both places.
For queries it's all fine, but note for mutations that the rules you define around Ents assume you're modifying them through Ents. e.g. you won't get cascading deletes if you delete through db which is why it's best practice to separate which tables are Ent tables.
You can always move away from Ents by defining the fields & join tables that it defines on your behalf- you can even go to the dashboard and download the current schema e.g.. And then move the data retrieval to vanilla commands. But that would probably be a lot of code to rewrite.
Ents shouldn't lag behind vanilla features too much. Code snippets and helpers libraries don't always work out of the box though - since those might assume a db object. You can write vanilla queries against it today - though I just learned the DataModel type doesn't include the Ents tables, so db.query and co. won't give you type safe access to the join tables, e.g.Okay, my takeaway is that it's easy-to-moderate difficulty to change the scope of tables that are defined as Ents. So, if I foresee a many-to-many relationship, bias toward defining those tables as Ents.
Not much to add here, recap:
1. Up to you whether you will hide ctx.db or use it alongside ctx.table. The Ents recommended path is to choose which tables are used via which interface, and don't mix them. Ideally you'll migrate entirely to Ents to keep your codebase consistent and simple.
2. It's unlikely Convex itself will evolve so rapidly that Ents wouldn't catch up. It's a TS library with fairly small footprint, worst case you can fork it and do anything you'd like with it. (but our intention is to keep it up-to-date, just like convex-helpers)
3. Overlap between convex-helpers and Ents: helpers have some relationship helpers, but they lack a lot of the functionality from Ents. The other functionality in convex-helpers you can use alongside Ents (for example migrations).
Ents are not perfect, you'll be living more on the bleeding edge of what's possible. Whether you're willing to take that risk is up to you.
Thanks michal, i am leaning toward going full Ents