2. Migrating from Convex

Every difference below was checked against the code, and the ones marked measured were run against the binary. What could not be checked is under "Not verified" at the end. License reminder: the Convex backend is FSL. NotusBase copies behavior, never code.

What stays the same

• The convex npm package, unchanged: convex/values, convex/server, the ConvexClient and ConvexHttpClient clients and the convex/react hooks. The sync route accepts any client version.
• Folders and files: convex/schema.ts, convex/*.ts, convex/_generated/, convex/http.ts, convex/crons.ts, convex/auth.config.ts, convex.json.
• query, mutation, action, internal*, httpAction, v.* validators, ConvexError, ctx.runQuery/runMutation/runAction, ctx.scheduler, ctx.storage, ctx.auth.getUserIdentity(), paginate, withIndex, withSearchIndex, ctx.vectorSearch, process.env, "use node".
• Reactivity: subscriptions re-execute on their own and deliver the new value, without reconnecting. Every session sees all queries at the same instant (per epoch).
• One transaction per mutation, with read-your-own-writes, rollback on error and retry on conflict (OCC).
• Export and import in the same zip as npx convex export, in both directions, with the same _ids.

What changes in the tooling

Without "use node", the server does not need Node. With the directive, it needs Node on the server (NOTUSBASE_NODE) and, for external packages, NOTUSBASE_NODE_PATH.

Without the directive, each npm package is resolved as in Convex, with the convex, module and browser conditions, the browser, module and main fields and the browser field map. That is how stripe and jose work in the version without node:*. The difference is process.env.NODE_ENV: Convex pins "production" in the bundle, and here the value comes from notusbase env.

What does not exist

What behaves differently

Ids and types

• Id format: table:identifier (measured: tasks:06gwnncd74fdbvr881dx). In Convex it is an opaque string. Code that interprets the id (splitting it, comparing a prefix, storing it elsewhere) must not rely on the format. v.id("table") checks the table by prefix. The identifier has 20 characters and rises with the creation time, like a ULID (48 bits of milliseconds and 52 random, lowercase base 32): sorting by _id is sorting by creation. A document imported from Convex keeps the id it had. A _storage id stays random, because knowing it is what gives access to the file.
• _creationTime: an integer in milliseconds (measured: 1793978499901). In Convex it is a number with a fraction.
• An optional field becomes a JSON column. SQL NULL is undefined, the text null is null. The consequence is the type ordering (above) and the slightly smaller 1 MiB ceiling (see 04).
• NaN, Infinity, -Infinity, -0: stored and returned as in Convex, in the same order (-Infinity, the numbers, -0, 0, Infinity, NaN), in indexes, filters, live queries, arguments, return values, export and import. One exception: -0 in a required top-level v.number() or v.float64() field becomes 0, because that field is a numeric column; there eq(-0) finds nothing and eq(0) finds both. In an optional, v.any(), union or nested field -0 stays -0. In the database, a numeric column holds ±Infinity as REAL and NaN as the text 'NaN'; a JSON column holds them as {"$float": ...}, as the Convex export writes them. The data screen shows them as the text NaN, Infinity and -Infinity, and saving such a record from that screen fails until the number is changed.
• Field name starting with $: rejected (Field name $x starts with a '$', which is reserved.).
• Field order in the document may differ. Do not rely on it.
• String comparison: gt, lte and eq compare the whole value. Convex treats "a" as a prefix of "a\0b".

ctx.db.get("table", id)

Both forms work, in get, patch, replace and delete: with the id alone and with the table name before it. An id from another table gives an error, as in Convex.

Writes and conflicts

• A short mutation never fails on conflict. If it takes less than 20 ms and conflicts, it runs serially inside the writer. A long mutation tries up to 8 times in parallel and returns a conflict error. Details in 04.
• Single writer. There is one SQLite writer with group commit (up to 256 mutations per transaction). Write throughput is that of one core; reads scale with isolates.
• Mutation retried on reconnect: the server keeps the result of requests for one to two hours. A reconnected client resends its unanswered mutations first, in order, with the ids they had: those the server already received from that client get the stored result, however long the client takes to send them; the first request with a new id ends the resends, and from then on requests run without a lookup. After a server restart the process does not know the client: what it sends in the first 10 s after a reconnect (counted on arrival, not counting the time the server stops reading because the client's queue is full) is looked up among the results stored before the restart, on this reconnect and on the next ones, until those results are two hours old. A client that comes back after a restart and after those 10 s with an unanswered mutation runs the mutation again.
• ctx.runMutation inside a mutation is atomic: if the call fails, only what it wrote is undone, including jobs it scheduled, even if the error is caught. Two parallel runMutation calls inside a mutation give an error.
• Module state. A module variable is shared between calls (the isolate is reused). The deploy detects a module variable written by a function, warns, and that code starts running in a fresh isolate per call. A component's client created at the top of a file, as the package's guide writes it, is not counted: new RateLimiter(components.rateLimiter, ...), that is, a class that comes from a package and takes components.<name> as its first argument. Calling its methods keeps the isolate reused; writing to a property of the client or replacing the variable still counts, and so does a class of the project. This is a net, not a proof: the deploy reads the project's code, not the packages', so a package whose client keeps data of the call on itself would hand it to the next call. The clients of @convex-dev/rate-limiter, @convex-dev/stripe and @convex-dev/better-auth were read and keep only their configuration, and a test calls each one as two users through the same isolate (notusbase/app/components/clients). A value a file copies from process.env when it loads, the Stripe client's key included, follows notusbase env set: when the environment changes, the code loads again in every isolate and in the "use node" process, and calls already running finish where they were. Math.random is seeded and the clock stops during the function, as in Convex.

Reads and filters

• filter becomes a WHERE in SQLite. The discarded row never reaches JS, but it counts towards the 32,000-read limit, as in Convex (measured: with the ceiling at 5, a filter over 12 rows that returns 1 fails with Too many documents read). Its bytes do not count towards the 16 MiB.
• paginate: key-based cursor. In a mutation and in search it sees its own writes, each in its place. The cursor ends in the document's id. A cursor made before 2026-11-11 ended in a row number and is refused as a cursor of another query.
• Text search: SQLite FTS5, kept in the same transaction as the write, so a query never sees a row without its index entry. Words joined by OR, the last one also as a prefix, ranked by FTS5's bm25. Pending writes of the mutation itself are seen, but without stripping accents when comparing (the FTS5 result strips them). Up to 1,024 results. A subscription runs again on any write to a row that passes its eq filters, whether or not the text has the words. Changing searchField under the same index name rebuilds the index on deploy, writes waiting while it reads the table (twice if the deploy then fails and the old index is rebuilt), and deploy --plan says so with the rows and an estimate measured on an M4.
• Reactivity range: when in doubt the range gets bigger, so a query may re-execute unnecessarily, never miss an update. With 256 or more dirty documents on one key in the same epoch, it re-executes without testing the range.
• Shared query: subscriptions with the same path and arguments run once for everyone, as long as the function does not read ctx.auth. If it starts reading it, each user gets their own query, for all arguments, until the next deploy.
• Stale read in the official client: ConvexClient.query answers from what it stored until the next transition when the same query has just finished. This is the client's behavior, not the server's. To read right after writing, use onUpdate (or ConvexHttpClient).

Schema

• The server creates the table, column, index and created at boot and on deploy, only adding. A column that left the schema while documents still hold a value in it blocks the deploy, as in Convex (measured: column outside schema.ts: tasks.priority, with a value in 12 documents (refusal)). Once every document is empty there, the deploy passes, the field disappears from the documents and the column stays in the table: tables and columns are never dropped. The way through is in Changing the schema with data. A search or vector index removed from the code is dropped.
• The deploy reads the whole table, in a separate isolate, when its type changed, and rejects a schema that the documents do not satisfy. defineSchema(..., { schemaValidation: false }) turns it off. A mutation from the old code, running during the deploy, can still write something the validation did not see.
• Writes through the PocketBase dashboard go through the schema validator.
• An index on a nested field works: .index("x", ["meta.level"]) becomes an expression index (nested_<table>_<name>).
• notusbase_* tables belong to the server and do not show up in ctx.db.query. Only _scheduled_functions and _storage show up, through ctx.db.system.

Errors

• In production, only ConvexError carries data to the client. Any other error becomes [Request ID: …] Server Error, and the detail goes to the log with the same id. That is how Convex works, but here it also applies to argument validation errors (measured: ArgumentValidationError and an invalid id arrive as Server Error). The reason goes to the log, with the rejected value hidden: notusbase logs --since 5m --text <Request ID> finds it. With NOTUSBASE_DEV_ERRORS=1 or notusbase dev, the detail reaches the client (table in the quick start).
• The error log carries convex/file.ts:line:column (source map); ConvexError generates no stack.

Actions, scheduler, HTTP

• Action: 1 s of CPU per stretch between awaits, 10 min in total. Action isolates are shared: whoever blows CPU or memory takes down the other actions in the same isolate (they come back with an error). In Convex each action is isolated.
• A scheduled action runs at most once; if the server dies midway, it is left as failed. A scheduled mutation runs exactly once. The job joins the mutation's transaction, so if it rolls back, the job never existed.
• Cron in UTC. The next run is stored in the database, so a restart neither repeats nor advances it. A run that has not finished does not get a second copy.
• httpAction lives at the root, next to the PocketBase routes (/api/..., /_/). Avoid paths that collide with them.
• fetch from inside an action does not reach loopback, private network or link-local (error internal destination ... refused; allow with NOTUSBASE_FETCH_ALLOW). notusbase dev allows loopback, so a local test server works there and not in serve.
• "use node" runs in a single Node process with all actions on the same event loop, with a memory ceiling for the whole process. It does not read pb_data, only writes to HOME, and fetch follows the filter above, but it does not contain hostile code: run only code you wrote or reviewed.

Authentication

• ctx.auth.getUserIdentity() works in all four contexts. It accepts (a) a PocketBase token from collections listed in NOTUSBASE_AUTH_COLLECTIONS (tokenIdentifier = pocketbase|users|<id>, subject = record id) and (b) a provider JWT in auth.config.ts (customJwt or OIDC).
• Verified-token cache: 30 s. An expired token drops the identity at the right time; the session switches user without reconnecting.
• A PocketBase login that stops being valid drops at once. Deleting the record, or changing its password or tokenKey (dashboard, records API, e.app.Delete in Go), refuses its token over HTTP right away, without waiting for the cache, and each open WebSocket session with that identity gets AuthError and closes: its subscriptions stop and the client must authenticate again. A token from auth.config.ts (OIDC, customJwt) is not a record here and holds until its exp, as in Convex. Deleting a whole login collection does not go through the record hooks: its open sessions hold until the token expires.
• There is no verified @convex-dev/auth. External providers (Clerk, Auth0) go through auth.config.ts; see "Not verified".
• Signup: closed by default in notusbase serve, on every start. NOTUSBASE_SIGNUP=1 opens it, if users is in NOTUSBASE_AUTH_COLLECTIONS. notusbase dev already turns both on, for testing.
• Login collections: at most one PocketBase collection, users by default. The dashboard, the deploy and the environment do not create another, and the server refuses to start if NOTUSBASE_AUTH_COLLECTIONS names a collection that is not an auth collection. To separate audiences, use roles in a table, such as members in the modeling guide. If the app brings its own users table, like Convex Auth, PocketBase's login collection steps aside and login lives in the library, checked through auth.config.ts.
• Client login: with ConvexProviderWithAuth and your own useAuth. @convex-dev/auth does not work here: a project's login is PocketBase's users collection, or the system's own code. PocketBase's routes and a signed-in client are in Login. The PocketBase token comes out with iat and jti, so the official client renews it on its own.

Files

• generateUploadUrl signs a 1 h, single-use link. The file goes to disk at pb_data/storage/_storage (outside the main SQLite) and a row in _storage holds the metadata. Deleting joins the transaction; the file leaves the disk after the commit. GET serves Range, with CSP sandbox and nosniff.
• ctx.storage.getUrl returns a URL on the server itself.
• The storage id is _storage:<identifier>, in the same table:identifier format as the others. v.id("_storage") accepts it; code that passes the bare identifier fails validation.

Data

• notusbase import reads the Convex zip with the same _ids, references, int64, bytes and files. The tables of a component installed in convex/convex.config.ts go into that component, with the same ids, and notusbase export writes them back under _components/ (since 2026-11-11). A component the project does not install, Convex Auth tables and users are left out, with a warning and --skip. _creationTime keeps the fraction it had, and so the order: a table that receives ids from Convex gets a column with the exact time and an index on it, and reads by _creationTime, _id as Convex does. The NotusBase zip goes into Convex with npx convex import --replace-all (measured on the local backend).
• An external sqlite3 cannot run integrity_check on the live database because it does not know notusbase_key: use notusbase check --dir.
• The database is SQLite with synchronous=NORMAL and a 1 s sync: a power loss can lose up to ~1 s of acknowledged commits . Self-hosted Convex with the same setting has the same window; cloud Convex does not.

Migration checklist

1. Copy convex/ to a new project and run npm install convex typescript. Do not change the convex version for no reason; tested with 1.49.0.
2. Look for what does not exist: components that need what NotusBase does not give a component yet (see the table above; the call fails saying what is missing), ctx.db.get(/patch(/replace(/delete( with two arguments, a cursor assumed to be a stable string, interpretation of the id format.
3. Run notusbase dev, which shows error details. Read the warnings about module state and diverging columns.
4. Set the variables. The deploy lists them: warning: N variables read in process.env with no value on the server: .... Set each one with notusbase env set <name>, which asks for the value. A read that already allows for no value is left out of the list: process.env.X ?? "default", || "default", &&, the test of an if or a ? :, and a default in const { X = "default" } = process.env.
5. Check the crons. notusbase sql "select name, next from _crons" shows each one from convex/crons.ts with its next run. They run in UTC.
6. Write a test that depends on the result, not the status: see notusbase/example/test.mjs.
7. Swap CONVEX_URL in the clients for the NotusBase address. Test reconnection, server crash and subscription.
8. Review the limits in 04 against your heaviest queries: the 1 s of a query or mutation includes the database here.
9. Move the data: npx convex export --include-file-storage, notusbase import with --skip for what NotusBase does not import, and check the per-table counts it prints.
10. Production: proxy, backup, secret and origins, and the rules in 03.

Not verified

• An external authentication provider (Clerk/Auth0) with auth.config.ts, and @convex-dev/auth.
• Importing a production Convex export (it only ran with fake data on the local backend).
• @convex-dev/* packages that are not components.
• The queue module against the original component on a real Convex: it only ran on NotusBase.
• That Convex also hides validation errors in production: I read it in the documentation, I did not run it.