#migrations dry run

19 messages · Page 1 of 1 (latest)

modest jungleBOT
#

Hi @last sonnet. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

#

This output shows a dry run of a migration in Convex. Dry runs are a useful feature that allows you to test what a migration would do without actually committing any changes to your database.

In this case, you're seeing the output of a migration called clearWorkspaceTaskField that's removing the taskIds field from documents in what appears to be a workspace table. The dry run shows:

  1. The "before" state of a document with the taskIds field (which is an empty array)
  2. The "after" state where the taskIds field has been removed
  3. The migration throwing a DRY RUN error, which is expected behavior to prevent changes from being committed

This is exactly how dry runs are designed to work in Convex. As mentioned in the Migrations Component documentation, you can run a dry run by passing dryRun: true to any runner or runOne command:

npx convex run migrations:runIt '{dryRun: true}'

The dry run will process one batch of documents and then throw an error to prevent any changes from being committed, allowing you to see what the migration would have done. This is particularly valuable for validating that your migration does what you expect before running it on your actual data.

The error message also includes useful information about the migration's progress, showing it processed 1 document and providing a cursor that could be used to continue the migration from this point if needed.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@last sonnet Kapa.ai is still learning and improving, please let me know how I did by reacting below.

last sonnet
#

my migration is an internal migration with name: migrations/clearWorkspaceTaskField:clearWorkspaceTaskField

how to run it with the dashboard

#

@modest jungle im trying to run it via the dashboar with
{
dryRun: false,
fnHandle: "",
name: "migrations/clearWorkspaceTaskField",
}

modest jungleBOT
#

Let me check the knowledge base for you again. One moment! :books:

#

I see you're trying to run a migration from the Convex dashboard. Based on the parameters you're using, there are a few adjustments needed to make it work correctly.

When running migrations from the dashboard, you need to use the correct format for the arguments. According to the documentation, there are a few ways to run migrations:

If you're using the general-purpose migrations.runner() function (typically exported as run in your migrations file), you should use:

{
  "fn": "migrations/clearWorkspaceTaskField:clearWorkspaceTaskField",
  "dryRun": false
}

The fn parameter should include the full path to your migration function, including the file path and the function name after the colon.

Alternatively, if you've defined a specific runner for this migration (like export const runClearWorkspace = migrations.runner(internal.migrations.clearWorkspaceTaskField)), you could just run that function directly without parameters, or with:

{
  "dryRun": false,
  "cursor": null
}

The name and fnHandle parameters you're using don't match the expected format for the migrations component. The name parameter should be in the fn parameter as shown above.

For more details on running migrations, you can refer to the Migrations Component documentation.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@last sonnet Kapa.ai is still learning and improving, please let me know how I did by reacting below.

last sonnet
#

[Request ID: d5c65a2b665cdb14] Server Error
Uncaught Error: Could not find public function for 'migrations/clearWorkspaceTaskField' in 'migrations'. Did you forget to run npx convex dev or npx convex deploy?
at async handler (../node_modules/.pnpm/@[email protected]._e037858ecf7dcdbe98314e72b7d6f236/node_modules/@convex-dev/migrations/src/component/public.ts:87:24)

#

@modest jungle
[Request ID: d5c65a2b665cdb14] Server Error
Uncaught Error: Could not find public function for 'migrations/clearWorkspaceTaskField' in 'migrations'. Did you forget to run npx convex dev or npx convex deploy?
at async handler (../node_modules/.pnpm/@[email protected]._e037858ecf7dcdbe98314e72b7d6f236/node_modules/@convex-dev/migrations/src/component/public.ts:87:24)

modest jungleBOT
#

Let me check the knowledge base for you again. One moment! :books:

#

Based on the error message you're seeing, there's a problem with how you're trying to access your migration function. The error indicates that Convex can't find a public function called 'migrations/clearWorkspaceTaskField' in the 'migrations' module.

This is likely happening because of one of these reasons:

  1. The function name format is incorrect. When running migrations, you need to use the full path including both the file name and the function name, separated by a colon.

  2. You haven't run npx convex dev or npx convex deploy recently, so your functions aren't properly registered with your deployment.

Here's how to fix it:

First, make sure you've run npx convex dev to register your functions with your deployment. This command keeps your backend code in sync with your deployment as explained in the documentation.

Then, when running the migration from the dashboard, use this format:

{
  "fn": "migrations:clearWorkspaceTaskField"
}

If your migration function is in a file other than migrations.ts, you'll need to use that filename instead. For example, if it's in clearWorkspace.ts, you would use:

{
  "fn": "clearWorkspace:clearWorkspaceTaskField"
}

The error specifically mentions that it couldn't find the function in 'migrations', which suggests that either:

  • Your function is defined in a different file
  • The function isn't properly exported
  • The function hasn't been registered with your deployment yet

As noted in one of the Discord support threads, the function name in the command needs to match the file name where the function is defined as discussed in this Discord thread.

#

If you continue to have issues, try running npx convex codegen --typecheck=disable to regenerate your API types without running a full typecheck.

Let me know if this resolves your issue!

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@last sonnet Kapa.ai is still learning and improving, please let me know how I did by reacting below.

last sonnet
#

@modest jungle Argument of type '{ auth: { store: FunctionReference<"mutation", "internal", { args: { sessionId?: Id<"authSessions"> | undefined; type: "signIn"; userId: Id<"users">; generateTokens: boolean; } | { type: "signOut"; } | ... 9 more ... | { ...; }; }, string | ... 3 more ... | null, string | undefined>; }; migrations: { ...; }; }' is not assignable to parameter of type 'MigrationFunctionReference | MigrationFunctionReference[] | undefined'.

when I try to use internal

import { Migrations } from "@convex-dev/migrations";
import { components, internal } from "./_generated/api.js";
import { DataModel } from "./_generated/dataModel.js";

export const migrations = new Migrations<DataModel>(components.migrations);
export const run = migrations.runner(internal);

#

@modest jungle Argument of type '{ auth: { store: FunctionReference<"mutation", "internal", { args: { sessionId?: Id<"authSessions"> | undefined; type: "signIn"; userId: Id<"users">; generateTokens: boolean; } | { type: "signOut"; } | ... 9 more ... | { ...; }; }, string | ... 3 more ... | null, string | undefined>; }; migrations: { ...; }; }' is not assignable to parameter of type 'MigrationFunctionReference | MigrationFunctionReference[] | undefined'.

when I try to use internal

import { Migrations } from "@convex-dev/migrations";
import { components, internal } from "./_generated/api.js";
import { DataModel } from "./_generated/dataModel.js";

export const migrations = new Migrations<DataModel>(components.migrations);
export const run = migrations.runner(internal);

modest jungleBOT
#

Let me check the knowledge base for you again. One moment! :books:

#

I can see you're encountering a TypeScript error when trying to use the Migrations component in Convex. The issue is with how you're passing the internal object to the migrations.runner() function.

The error occurs because you're passing the entire internal object to the runner() function, but this function expects either a specific migration function reference or an array of migration function references.

Here's how to fix it:

// Don't pass the entire internal object
export const run = migrations.runner(); // Use this for a general-purpose runner

// OR specify a specific migration function
export const runSpecific = migrations.runner(internal.migrations.yourMigrationFunction);

The migrations.runner() function can be used in two ways:

  1. Without arguments - creates a general-purpose runner that you can invoke with a function name parameter
  2. With a specific migration function reference - creates a dedicated runner for that specific migration

According to the Migrations Component documentation, you should either:

  • Create a general-purpose runner with export const run = migrations.runner(); and then run it with a function name parameter
  • Create a specific runner for a single migration with export const runIt = migrations.runner(internal.migrations.setDefaultValue);

The error you're seeing is because the internal object contains all your internal functions, not just migration functions, and the runner expects only migration function references.

After making this change, you can run your migration using the CLI:

npx convex run migrations:run '{fn: "migrations:yourMigrationFunction"}'
#

Or if you created a specific runner:

npx convex run migrations:runSpecific

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: