Add `--db-image` argument to `wasp start db` command #3182

cprecioso · 2025-09-22T12:36:14Z

Fixes Enable specifying custom Docker image for managed dev database wasp db start #1414
This PR was previously merged as Add --image argument to wasp start db command #3177 before it was ready, and rapidly reverted

Adds an optional --db-image argument to the wasp start db command, allowing users to specify a custom Docker image for their development 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 locally.

Changes

Added --db-image argument parsing
Modified wasp start db to accept and use custom Docker images
Added documentation highlighting the extensions use case

Usage

# Use default PostgreSQL image (uses `postgres`)
wasp start db

# Use specific PostgreSQL version
wasp start db --db-image postgres:15

# Use PostgreSQL with PostGIS extension
wasp start db --db-image postgis/postgis:14-3.2

# Use PostgreSQL with pgvector extension
wasp start db --db-image pgvector/pgvector:pg16

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-22T13:48:08Z

Deploying wasp-docs-on-main with Cloudflare Pages

Latest commit:	`658f0dc`
Status:	✅ Deploy successful!
Preview URL:	https://059fd91c.wasp-docs-on-main.pages.dev
Branch Preview URL:	https://db-image-arg.wasp-docs-on-main.pages.dev

View logs

cprecioso · 2025-09-22T13:51:49Z

Tested with PostGIS and pgvector images, both work fine!

sodic

I like the feature.

I want to request one main change: We should refactor the system in a way that the default case is just an instantiation of a particular image, not a special procedure.

In other words, we want wasp start db to mean (as closely as possible) wasp start db --image postgres, both in terms of how we implement it and how we communicate it with users. There are a few comments talking about what this means for different parts of our code.

Other than that, I found some small stuff: missing help text, function name, etc.

sodic · 2025-09-23T16:47:37Z

waspc/ChangeLog.md

+### 🔧 Small improvements
+
+- You can now specify which PostgreSQL image to use in `wasp start db` with the `--image` argument. ([#3182](https://github.com/wasp-lang/wasp/pull/3182))


I'd list this as a new feature, not a small improvement.

It may not be useful to everybody but it is a feature :)

sodic · 2025-09-23T17:27:55Z

waspc/cli/exe/Main.hs

        title "  IN PROJECT",
        cmd   "    start                 Runs Wasp app in development mode, watching for file changes.",
-        cmd   "    start db              Starts managed development database for you.",
+        cmd   "    start db [--image <image>]",


We're missing this help text when we run wasp db. Plus, we could include some examples for wasp start:

Include some examples for wasp start in wasp db?

sodic · 2025-09-23T17:29:30Z

web/docs/data-model/databases.md

+You can also specify a custom Docker image to use for the database with the `--image` option. This is particularly useful when you need PostgreSQL with specific extensions (like PostGIS for geographic data, pgvector for embeddings, etc.):
+
+```bash
+# Use default PostgreSQL image


I think we should say what the default is, maybe even communicate it as:

wasp start db is a shorthand for wasp start db -- image postgres

sodic · 2025-09-24T07:31:01Z

waspc/cli/src/Wasp/Cli/Command/Start/Db.hs

+start args = do
+  startDbArgs <-
+    parseArguments "wasp start db" startDbArgsParser args
+      & either (E.throwError . CommandError "Invalid arguments") return


No need to change anything here, just FYI.

I rarely use & in Haskell. I believe it's more idiomatic doing stuff from right to left (which is unfortunate) so I'm not used to seeing this.

Here's how I would probably write this:

start args = do startDbArgs <- either (E.throwError . CommandError "Invalid arguments") return $ parseArguments "wasp start db" startDbArgsParser args

Or even like this:

start args = do startDbArgs <- case parseArguments "wasp start db" startDbArgsParser args of Left err -> E.throwError $ CommandError "Invalid arguments" err Right parsedArgs -> return parsedArgs

You can pick whatever you like the most, all options are perfectly valid.

Opposite opinion: I think the current code with the & is the best one.

While & is not that popular as $, I don't see any reason why one would not use it in appropriate places("appropriate" being the key here).

In Haskell, you anyway read both from left to right and right to left, it depends on the situation, so there is no golden rule here.

It does make sense to stick with how people normally write Haskell, so I agree one shoudln't go crazy with &, but here I think its usage is perfect, because it allows you to read code in the right order -> business logic is in focus, error handling comes after (and is even nicely indented). So I can read it as do this, but if error this and I think that is perfect.

In this case it's written like that for consistency, like in here:

wasp/waspc/cli/src/Wasp/Cli/Command/CreateNewProject.hs

Lines 32 to 36 in 1129a07

createNewProject :: Arguments -> Command ()

createNewProject args = do

newProjectArgs <-

parseArguments "wasp new" newProjectArgsParser args

& either Common.throwProjectCreationError return

I think a good idea in general for this would be to start using Options.Applicative for all of our CLI argument parsing, not just occasionally.

sodic · 2025-09-24T07:35:06Z

waspc/cli/src/Wasp/Cli/Command/Start/Db.hs

+        ++ ( if isJust customImage
+               then [" ℹ Using custom Docker image: " <> dockerImage, ""]
+               else []
+           )
+        ++ [ "Additional info:",
+             " ℹ Connection URL, in case you might want to connect with external tools:",
+             "     " <> connectionUrl,
+             " ℹ Database data is persisted in a docker volume with the following name"
+               <> " (useful to know if you will want to delete it at some point):",
+             "     " <> dockerVolumeName
+           ]


At this point (and perhaps even at an earlier one), I think it makes sense to extract these messages into their own variables inside the where block. There's a lot of nesting.

@cprecioso What do you think?

Actually the nesting was basically unnecessary, now it's all in the top level. I don't really like extracting it somewhere else, and now it's simpler, so I think I'll leave it as-is.

sodic · 2025-09-24T07:40:47Z

waspc/cli/src/Wasp/Cli/Command/Start/Db.hs

    "To run PostgreSQL dev database, Wasp needs `docker` installed and in PATH."
  throwIfDevDbPortIsAlreadyInUse

+  let dockerImage = fromMaybe "postgres" customImage


I believe we should do this part outside of the calling function and send the final image in as an argument:

startPostgresDevDb :: Path' Abs (Dir WaspProjectDir) -> String -> String -> Command () startPostgresDevDb waspProjectDir appName image = do

There isn't really a reason for this function to take in an optional and then
Also, I see the name was changed from "postgres" to "postgre." I believe this is incorrect: the official name of the project is "PostgreSQL" and its nickname is "Postgres." (wikipedia).

Huh weird thing about the Postgres thing, I didn't realize!

sodic · 2025-09-24T07:42:50Z

waspc/cli/src/Wasp/Cli/Command/Start/Db.hs

+        ++ ( if isJust customImage
+               then [" ℹ Using custom Docker image: " <> dockerImage, ""]
+               else []


I don't think we need any special text here. We should always say "Using Docker image ...."

The default case should just be a default value for something, not a special procedure. This means:

We set the default value at the top of the "system."

Everything else is completely agnostic on whether it's working with the default value or the custom value.

sodic · 2025-09-24T07:51:48Z

waspc/cli/src/Wasp/Cli/Command/Start/Db.hs

+-- | Command-line arguments for `wasp start db`
+data StartDbArgs = StartDbArgs
+  { customDbImage :: Maybe String
+  }


Since we have all this parsing logic in the same file, I suggest moving this datatype below start.

Our rule is:

Exported stuff before private stuff

If A is used in B, A should come as soon as possible after B without breaking the first rule (I think Clean Code has a nice name for this rule, can't remember now)

Unfortunately, many files don't stick to this rule since we can't automate it (at least I think we can't) and sometimes forget. But when we remember, we should follow it :)

Do we have super strict rule for this? If we do I have to admit I forgot it.
My rule is, make it read like a story (Clean Code also). Almost always that will match what you wrote above, but there could be some exceptions.

Martinsos

Nice stuff! Some good comments were already left by others, but I also left some of my own.

One thing I am wondering about is the workflow itself -> let's say somebody is using custom dev db, do they have to keep passing this arg all the time? Is that a bit cumbersome? I guess they will have to set up some kind of small shell script to serve as a runner so they don't have to repeat it.

I commented in Railway (or was it Fly) PR also on this. I wonder if it would make sense, from the DX perspective, to actually also have a central place to define a default database image, that would be used both in dev and when deploying. Since at the end, it is a property of the full stack app -> when you are building your wasp app, you are assuming some kind of database, and ideally you would use the same exact database setup both in dev and in prod. I am sure that might not always be so, but it would be nice if this primary use case is supported by us.

This doesn't have to be done in this issue, but I would like us to think/discuss about it, now that we are doing this.

waspc/cli/exe/Main.hs

waspc/cli/src/Wasp/Cli/Command/Start/Db.hs

Martinsos · 2025-09-24T09:55:00Z

waspc/cli/src/Wasp/Cli/Command/Start/Db.hs

+-- | Command-line arguments for `wasp start db`
+data StartDbArgs = StartDbArgs
+  { customDbImage :: Maybe String
+  }


Do we have super strict rule for this? If we do I have to admit I forgot it.
My rule is, make it read like a story (Clean Code also). Almost always that will match what you wrote above, but there could be some exceptions.

waspc/cli/src/Wasp/Cli/Command/Start/Db.hs

Martinsos · 2025-09-24T10:00:22Z

waspc/cli/src/Wasp/Cli/Command/Start/Db.hs

+start args = do
+  startDbArgs <-
+    parseArguments "wasp start db" startDbArgsParser args
+      & either (E.throwError . CommandError "Invalid arguments") return


Opposite opinion: I think the current code with the & is the best one.

While & is not that popular as $, I don't see any reason why one would not use it in appropriate places("appropriate" being the key here).

In Haskell, you anyway read both from left to right and right to left, it depends on the situation, so there is no golden rule here.

It does make sense to stick with how people normally write Haskell, so I agree one shoudln't go crazy with &, but here I think its usage is perfect, because it allows you to read code in the right order -> business logic is in focus, error handling comes after (and is even nicely indented). So I can read it as do this, but if error this and I think that is perfect.

waspc/cli/src/Wasp/Cli/Command/Start/Db.hs

web/docs/data-model/databases.md

cprecioso · 2025-09-25T13:10:59Z

@Martinsos

I wonder if it would make sense, from the DX perspective, to actually also have a central place to define a default database image

Yes, I agree. This also makes me feel like what @infomiho once said about having a deployment config file might also make sense. As you said, I think it might be out-of-scope for this PR, but we could start looking into it. (If/when we conclude that custom DB images are a feature that people do use)

cprecioso · 2025-09-25T13:27:18Z

@sodic @Martinsos ready

Martinsos · 2025-09-25T14:23:54Z

@Martinsos

I wonder if it would make sense, from the DX perspective, to actually also have a central place to define a default database image

Yes, I agree. This also makes me feel like what @infomiho once said about having a deployment config file might also make sense. As you said, I think it might be out-of-scope for this PR, but we could start looking into it. (If/when we conclude that custom DB images are a feature that people do use)

I do think they are needed for sure, the custom DB images. But sure more data will be helpful.

There is one older related issue: #169 . And I know Miho did some work on it in the meantime where i also aprticipated but can't find it right now, I asked him to link it there.

EDIT: I also created issue for it here: #3193 .

Martinsos

Couple of comments, but once you resolve them, I am good with merging!

Martinsos · 2025-09-25T14:29:02Z

waspc/cli/exe/Main.hs

-              "                    supplied migration name or asking for one.",
+              "  start [--db-image <image>]   Alias for `wasp start db`.",
+              "                               Starts managed development database for you.",
+              "                               Optionally specify a custom Docker image."


Not the same as for wasp start db (missing "with --db-image). I would add it here or remove it up there.

I don't get this comment, can you clarify? I do handle the argument in both cases.

Aha sorry, I should have been more verbose! So CLI docs for wasp start db are very similar, but a bit different, and there is no reason for them to be different, so I was suggesting to make them the same. THe difference is in "with --db-image" part).

ahh understood, my eyes were skipping over that haha

waspc/cli/src/Wasp/Cli/Command/Start/Db.hs

waspc/ChangeLog.md

web/docs/data-model/databases.md

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 mentioned this pull request Sep 22, 2025

Add --image argument to wasp start db command #3177

Merged

cprecioso added 2 commits September 22, 2025 15:33

Fix

85edcbb

Rename data member

2644208

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

cprecioso requested a review from Martinsos September 22, 2025 13:51

Add caveat to docs

dcdd083

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

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

Typo

b08f5b3

cprecioso mentioned this pull request Sep 22, 2025

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

Merged

Add changelog

008b004

sodic requested changes Sep 24, 2025

View reviewed changes

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

Martinsos reviewed Sep 24, 2025

View reviewed changes

cprecioso added 7 commits September 25, 2025 14:38

Fixes

4c6ddc2

Merge branch 'main' into db-image-arg

f96a943

Comment

7e70d20

Docs

9189200

comment

0be6c33

Rename

f01ae55

Extract

3786a5c

cprecioso added 2 commits September 25, 2025 15:08

Default postgres

7b8172e

Reorder

3ad3ea1

cprecioso added 7 commits September 25, 2025 15:14

Rename option

4c4283c

Remove unneeded comments

de04937

Rename

8326fae

Dots

c37184d

Headings

0ae96d4

Typo

9a77d0f

Explanation

11f79b3

Martinsos approved these changes Sep 25, 2025

View reviewed changes

cprecioso changed the title ~~Add --image argument to wasp start db command~~ Add --db-image argument to wasp start db command Sep 26, 2025

cprecioso added 4 commits September 26, 2025 10:13

Extract default value

579006c

link

f882fda

Fixes

658f0dc

Fix comment

45855d7

cprecioso merged commit a8ffba4 into main Sep 26, 2025
7 checks passed

cprecioso deleted the db-image-arg branch September 26, 2025 09:29

infomiho pushed a commit that referenced this pull request Sep 29, 2025

Add --db-image argument to wasp start db command (#3182)

2cc08ec

		### 🔧 Small improvements

		- You can now specify which PostgreSQL image to use in `wasp start db` with the `--image` argument. ([#3182](https://github.com/wasp-lang/wasp/pull/3182))

	createNewProject :: Arguments -> Command ()
	createNewProject args = do
	newProjectArgs <-
	parseArguments "wasp new" newProjectArgsParser args
	& either Common.throwProjectCreationError return

Uh oh!

Add --db-image argument to wasp start db command #3182

Add --db-image argument to wasp start db command #3182

Uh oh!

Conversation

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

Uh oh!

Changes

Usage

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!

cprecioso commented Sep 22, 2025

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!

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!

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 24, 2025 • edited by infomiho 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!

Martinsos left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cprecioso commented Sep 25, 2025

Uh oh!

cprecioso commented Sep 25, 2025

Uh oh!

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

Uh oh!

Uh oh!

Martinsos 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!

Choose a reason for hiding this comment

Add `--db-image` argument to `wasp start db` command #3182

Add `--db-image` argument to `wasp start db` command #3182

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 by infomiho

Loading

Martinsos commented Sep 25, 2025 •

edited

Loading