Add `--db-image` argument to `wasp-app-runner` #3183

cprecioso · 2025-09-22T12:48:37Z

On top of Add --db-image argument to wasp start db command #3182

Adds an optional --db-image argument to the run-wasp-app command, allowing us to specify a custom Docker image for the database.

This is part of #3174. We're adding ask-the-documents to the repo, which needs a specific PostgreSQL extension. This way we can more easily test the app.

Changes

Modified run-wasp-app to accept and use custom Docker images
Added explanation to README

Note

🤖 Generated with Claude Code
and 👨🏻 reviewed and edited by a person

Allows users to specify a custom Docker image when starting the development database. Usage: wasp start db --image postgres:15 This enables developers to test with different PostgreSQL versions or custom database images.

- Note default postgres image in help text - Add error handling for unrecognized arguments - Use fromMaybe to simplify image selection logic - Add comprehensive documentation in CLI and database docs

- Replace manual argument parsing with Options.Applicative parser - Move parser to top level as requested - Add note about PostgreSQL extensions use case in documentation - Remove redundant CLI documentation as requested

- Change StartDbArgs from newtype to data type - Move startDbArgsParser below the main start function - Parse arguments as the first operation in start function

cloudflare-workers-and-pages · 2025-09-22T14:11:56Z

Deploying wasp-docs-on-main with Cloudflare Pages

Latest commit:	`9d09644`
Status:	✅ Deploy successful!
Preview URL:	https://faf2c3f8.wasp-docs-on-main.pages.dev
Branch Preview URL:	https://image-arg-for-wasp-app-runne.wasp-docs-on-main.pages.dev

View logs

FranjoMindek

I think we can make the db-image configuration global rather than local.
Very straightforward and clean RP otherwise.

wasp-app-runner/src/args.ts

sodic

I have a concern similar to what I've voiced in #3182 (review).

Details here: #3183 (comment)

package.json

wasp-app-runner/README.md

sodic · 2025-09-24T08:28:16Z

wasp-app-runner/src/args.ts

  mode: Mode;
  pathToApp: PathToApp;
  waspCliCmd: WaspCliCmd;
+  dbImage?: string;


It seems this code has the same problem I talked about in my review of #3182 (review).

The "optionality" of dbImage is stretching itself too deep into the code. The default value should be handled as soon as possible. Most of the code shouldn't even know whether it's working with a default value or a custom value.

Think of it like this:

If we want to change the default value, the change should be in a single, obvious place. And the place should be the same for all flags/default values. We shouldn't have to dig all the way down to specific functions to change specific values.

Btw, am I missing something here? Since all other values are handled this way already and only the new one isn't, it's possible I'm not seeing what you're seeing.

I did it on purpose really, because of two reasons:

IMO semantically, it doesn't make sense to handle the default value in the CLI parsing level. Imagine we add support for a MySQL DB, then the default value of --db-image would actually be dynamically determined through the flow of the program, since we wouldn't want to set postgres image then, but a mysql one.

You can see this in the current code where the sqlite and postgres drivers have the same input parameters, so if I'm marking the dbImage as required and giving it a value at the top-level, I'm at some point passing dbImage: postgres into the sqlite driver. Of course (1) that's a no-op, and (2) nothing a refactor can't fix. But it points to this issue I'm talking about.

The fact that we are using a default value or not is sometimes relevant. For example, in the Railway PR, we need to set some variables if we're not using the default image. Of course, here's not an issue, but in my mind they're both working at the same level of abstraction.

But yeah this is me overvaluing a "correct" implementation ready to get extended, and undervaluing the straightforward-ness to handle this at the top level.

Wdyt?

But yeah this is me overvaluing a "correct" implementation ready to get extended, and undervaluing the straightforward-ness to handle this at the top level.

This is not clear to me hm, why do you think you are overvaluing a correct implementation vs simpler implementation? I think @sodic was also pushing for the most correct implementation.

I am not sure if I am getting the whole thing right. I think what you are saying is, we can, in case when CLI arg is not provided, set it to the default value right at the top, or we can recognize it is not set (set it to Nothing), and then when we want to do something with it, we can at that moment decide how to handle that and grab that default value from somewhere.

I think @sodic suggested the first approach because it means you have that logic of "what do I do when it is empty, aha I set it to default" at only one place in the code, avoiding duplication and desync in the future.

We could alternatively have one central function which does this ("give me the value of db docker image") and then leave the value of image to be Nothing, and then expect other parts of code to call that function. This gives the rest of the code more knowledge, because there is extra state of Nothing that they can react on (if relevant), but it does leave some extra space for a mistake, since they might not call that function as intended and do something else, by accident.

So first approach is simpler, and less code, but one "state" less, therefore less "knowledge" in the system.
Second approach is more complex, more code, more space for future mistakes, but one "state" more and more "knowledge" in the system.

I would say, unless it is clear that more knowledge is useful, or that it feels semantically correct (I know this sounds vague, but sometimes it just makes sense, I can't say right now because I am not immersed enough into this code), let's go for simpler option (approach one).

Btw I didn't get the point with mysql and postgres, so my bad if there was something there that would inform this discussion further. I do like the idea of tying up the default docker image with the default db system at the type (or some hm) level, if that is what you are suggesting.
Aaaaah I get what you mean now. If user set db.system to mysql, then we wouldn't set the value of --db-image to postgres, but to mysql docker image. Ok, true, that makes sense to me. But we can just say in the CLI docs that we will set it to default image for their chosen db system. We could even dynamically determine which one is that, as you said :D.

why do you think you are overvaluing a correct implementation vs simpler implementation?

oof not calling the other thing "incorrect", sorry! just that IMO with the constraints i had in mind, that was the most semantically accurate.

or that it feels semantically correct (I know this sounds vague, but sometimes it just makes sense, I can't say right now because I am not immersed enough into this code),

yeah this, it felt correct

Ok, I don't have anything else to say here so I will let the two of you figure it out, as I think @sodic has a better grasp of the code than me.

IMO semantically, it doesn't make sense to handle the default value in the CLI parsing level. Imagine we add support for a MySQL DB, then the default value of --db-image would actually be dynamically determined through the flow of the program, since we wouldn't want to set postgres image then, but a mysql one.

Me personally, I would still do it at the start of the program.
If above happens we will most likely need to parse the AppSpec to know what to do with the application (it also includes the prisma schema).

So the CLI and the AppSpec would be the two configuration inputs into the program.
As is usually with these programs, CLI would override the AppSpec provided values.

If so I would declare default values as part of the AppSpec parsing process.

That way we:
We have a single source of truth for configuration.
The information is known at the start of the program. If we ever need it at some other place we don't have to refactor the code to move the default value declaration to shared parent.
wasp-app-runner core/driver has to knew less about how Wasp applications work.

My thinking is if this operation can be overriden at the top, why not just default value it at the top?
The program must work with values defined at the top anyway.
This way we don't have to care about undefined values in the core/driver itself.

You can see this in the current code where the sqlite and postgres drivers have the same input parameters, so if I'm marking the dbImage as required and giving it a value at the top-level, I'm at some point passing dbImage: postgres into the sqlite driver. Of course (1) that's a no-op, and (2) nothing a refactor can't fix. But it points to this issue I'm talking about.

We shouldn't enforce the same interface if the needs are not the same.
I would say this was a mistake on our part.

We will have some branching logic no matter the solution, but I'm sure we could abstract some docker behavior when we support multiple databases if we do it this way.

The fact that we are using a default value or not is sometimes relevant. For example, in the Railway PR, we need to set some variables if we're not using the default image. Of course, here's not an issue, but in my mind they're both working at the same level of abstraction.

Yes, if we don't mind if it's default or not, let's just combine all the input data at the top?

You can see this in the current code where the sqlite and postgres drivers have the same input parameters, so if I'm marking the dbImage as required and giving it a value at the top-level, I'm at some point passing dbImage: postgres into the sqlite driver.

This is a great observation, but my conclusion is different :)

The core problem is that our current implementation has a "type error." It's not a real type error, but our groupings and parameters are set up in a way that allows invalid states.
Effective TS explains this in Item 29: Prefer Types That Always Represent Valid States.

Specifically, the parameter combination of dbType: DbType, dbImage?: string does not properly model our constraints. We lose information and are forced to think about a state which shouldn't exist, dbType: SQLite, dbImage: somethingOtherThanUndefined.

That is the root issue we should address. I think we should address it as high up as possible and propagate this information through the type system.

This problem likely affects the CLI too - we shouldn't really allow users to set --db-image if they're using dev mode. We should instead tell them something like "You can only use --db-image in build mode." If I'm not mistaken, the current implementation will just ignore the --db-image argument when used in dev mode.

Imagine we add support for a MySQL DB, then the default value of --db-image would actually be dynamically determined

@FranjoMindek did a great job explaining this point.

Wasp app runner currently asssumes that "build" means "Use a postgres database" and "dev" means "Use an SQLite database."

If we do add MySQL, we'll have to break this assumption and pass an extra input to the runner - either the full app specification like Franjo suggested, or at least an argument specifying the database. In any case, the app runner will get more info and still be able to decide which default to use at the top-level.

Finally, notice how "dev" doesn't have to mean "Use an SQLite database." Apps in dev mode can also use Postgres and, if that becomes necessary, we will again want to communicate this through argument codependencies and the type system.

For example, let's assume we add MySQL to Wasp. Let's also assume we want to work with real databases in development, so we add a --db-type flag.

run-wasp-app dev should then allow the --db-type to be either SQLite, MySql, or PostgreSQL.

If --db-type is SQLite, then we don't allow a --db-image flag.

If --db-type is MySQL or PostgreSQL, then we allow a --db-image flag and choose an appropriate default if one isn't provided. We could even check the image compatibility with the database if we decide it's useful (but again, near the top level).

These constraints and codependencies between arguments should then again be properly modelled by the type system.

The fact that we are using a default value or not is sometimes relevant. For example, in the Railway PR, we need to set some variables if we're not using the default image. Of course, here's not an issue, but in my mind they're both working at the same level of abstraction.

I don't think those are related. Wasp app runner needs the image to start a docker container. It's not doing anything fancy and I'd expect it to stay that way.

Finally, @FranjoMindek said:

We shouldn't enforce the same interface if the needs are not the same.
I would say this was a mistake on our part.

Yes, I agree. We should drop the SetupDbFn type. It doesn't provide anything useful and just forces our drivers to have the same inputs. I think the correct way to handle this would be doing something like:

// This would be parsed somewhere up top // I'm making up type names and don't have this fleshed out, but you get the idea type DbConfig = { dbType: SQLite } | { dbType: PostgreSQL, appName: string, pathToApp: string, dbImage: string } export function setupDb(dbConfig: DbConfig): DbSetupResult { // ... }

Yep I see the point. So as far as I can see, due to the needs of the code right now, I'm just pushing the default value to as top as I can get it (argument parser). In the future if we add more DB systems, we can then try and model the types in the way of "Making illegal states invalid".

Nice, that's the best thing to do right now, I agree.

we can then try and model the types in the way of "Making illegal states invalid".

@cprecioso Do you mind creating an issue for this? 😬

Also, I still think we should warn the caller that this option can't be used in dev mode instead of silently ignoring it.

Martinsos

Others covered main stuff well, I just poped a couple of extra comments. I will remain in the role of weak reviewer here and just comment, I won'd be doing approving.

wasp-app-runner/README.md

cprecioso · 2025-09-26T13:11:03Z

Ready for re-review @sodic @FranjoMindek @Martinsos

FranjoMindek

From my side it's okay.
I didn't check comments left by others.

sodic

Good stuff, I'd just like us to inform the user about the inability to use --db-image in dev mode, both in the docs and when using the CLI.

sodic · 2025-09-30T15:47:33Z

wasp-app-runner/README.md

 DATABASE_URL=postgresql://postgres:devpass@localhost:5432/postgres
 ```

+#### Custom database image


The docs should mention that this can't be used in dev mode too.

Where did you get the impression that it can't be used on dev mode? It can.

sodic

Good to go!

sodic · 2025-10-01T09:43:03Z

wasp-app-runner/src/index.ts

+  if (dbImageArg && dbType !== DbType.Postgres) {
+    logger.error(
+      `The --db-image option is only valid when using PostgreSQL as the database.`,
+    );
+    process.exit(1);
+  }
+  const dbImage = dbImageArg ?? defaultPostgresDbImage;


It's a shame we had to push this all the way down here but I see no other way :/

cprecioso added 5 commits September 19, 2025 10:59

feat: add --image arg to wasp start db command

98e6366

Allows users to specify a custom Docker image when starting the development database. Usage: wasp start db --image postgres:15 This enables developers to test with different PostgreSQL versions or custom database images.

refactor: address review feedback for --image arg feature

02fbe50

- Note default postgres image in help text - Add error handling for unrecognized arguments - Use fromMaybe to simplify image selection logic - Add comprehensive documentation in CLI and database docs

refactor: use Options.Applicative for start db argument parsing

f3e029f

- Replace manual argument parsing with Options.Applicative parser - Move parser to top level as requested - Add note about PostgreSQL extensions use case in documentation - Remove redundant CLI documentation as requested

refactor: address final review comments

071dba6

- Change StartDbArgs from newtype to data type - Move startDbArgsParser below the main start function - Parse arguments as the first operation in start function

style: format code for consistency

eef03ef

cprecioso self-assigned this Sep 22, 2025

cprecioso force-pushed the image-arg-for-wasp-app-runner branch 2 times, most recently from d61b39e to 4a541ed Compare September 22, 2025 13:18

Initial impl

cd24309

cprecioso force-pushed the image-arg-for-wasp-app-runner branch from 4a541ed to cd24309 Compare September 22, 2025 13:22

cprecioso added 2 commits September 22, 2025 15:33

Fix

85edcbb

Rename data member

2644208

cprecioso changed the title ~~feat: add --image arg to wasp start db command~~ Add --db-image to wasp-app-runner Sep 22, 2025

cprecioso changed the title ~~Add --db-image to wasp-app-runner~~ Add --db-image argument to wasp-app-runner Sep 22, 2025

Correct documentation

7b687b9

cprecioso changed the base branch from main to db-image-arg September 22, 2025 14:08

cprecioso added 3 commits September 22, 2025 16:11

Merge branch 'db-image-arg' into image-arg-for-wasp-app-runner

fd11f79

More docs

7c5ce5d

Add caveat to docs

dcdd083

cprecioso force-pushed the db-image-arg branch from e278763 to dcdd083 Compare September 22, 2025 14:11

cprecioso marked this pull request as ready for review September 22, 2025 14:14

cprecioso added 3 commits September 22, 2025 16:15

Format

fee47c6

Typo

b08f5b3

Add changelog

008b004

FranjoMindek requested changes Sep 24, 2025

View reviewed changes

wasp-app-runner/src/args.ts Outdated Show resolved Hide resolved

sodic requested changes Sep 24, 2025

View reviewed changes

Martinsos reviewed Sep 24, 2025

View reviewed changes

wasp-app-runner/README.md Show resolved Hide resolved

wasp-app-runner/README.md Show resolved Hide resolved

This was referenced Sep 24, 2025

Add --db-image argument to wasp deploy railway #3184

Open

Add --db-image argument to wasp deploy fly #3187

Open

cprecioso added 19 commits September 25, 2025 14:46

Comment

7e70d20

Docs

9189200

comment

0be6c33

Rename

f01ae55

Extract

3786a5c

Default postgres

7b8172e

Reorder

3ad3ea1

Rename option

4c4283c

Remove unneeded comments

de04937

Rename

8326fae

Dots

c37184d

Headings

0ae96d4

Typo

9a77d0f

Explanation

11f79b3

Extract default value

579006c

link

f882fda

Fixes

658f0dc

Merge branch 'db-image-arg' into image-arg-for-wasp-app-runner

211b356

Merge branch 'db-image-arg' into image-arg-for-wasp-app-runner

3d8fd82

cprecioso force-pushed the image-arg-for-wasp-app-runner branch from 76b79c0 to 3d8fd82 Compare September 26, 2025 08:28

Base automatically changed from db-image-arg to main September 26, 2025 09:29

cprecioso added 2 commits September 26, 2025 11:31

Merge branch 'main' into image-arg-for-wasp-app-runner

9d09644

Bring to top

5724af6

FranjoMindek approved these changes Sep 29, 2025

View reviewed changes

sodic reviewed Sep 30, 2025

View reviewed changes

Error out if not Postgres

a301bb4

sodic approved these changes Oct 1, 2025

View reviewed changes

cprecioso merged commit dec52b8 into main Oct 1, 2025
2 checks passed

cprecioso deleted the image-arg-for-wasp-app-runner branch October 1, 2025 09:57

Uh oh!

Add --db-image argument to wasp-app-runner #3183

Add --db-image argument to wasp-app-runner #3183

Conversation

cprecioso commented Sep 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Uh oh!

cloudflare-workers-and-pages bot commented Sep 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying wasp-docs-on-main with Cloudflare Pages

Uh oh!

FranjoMindek left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sodic left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sodic Sep 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sodic Sep 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sodic Sep 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Martinsos left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

cprecioso commented Sep 26, 2025

Uh oh!

FranjoMindek left a comment

Choose a reason for hiding this comment

Uh oh!

sodic left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sodic left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Add `--db-image` argument to `wasp-app-runner` #3183

Add `--db-image` argument to `wasp-app-runner` #3183

cprecioso commented Sep 22, 2025 •

edited

Loading

cloudflare-workers-and-pages bot commented Sep 22, 2025 •

edited

Loading

sodic left a comment •

edited

Loading

sodic Sep 24, 2025 •

edited

Loading

sodic Sep 26, 2025 •

edited

Loading

sodic Sep 30, 2025 •

edited

Loading