ValueError: Port could not be cast to integer value when connecting to Qovery Postgres from Python

TL;DR

Use urllib.parse.quote on the password with safe='' and rebuild the URL, or just quote the password segment in place.

Steps

1. The password in the connection URL has to be percent-encoded before you hand the URL to your driver, because Qovery generates passwords with URL-significant characters like @, $, ?, and =. Use urllib.parse.quote on the password with safe='' and rebuild the URL, or just quote the password segment in place. The reporter confirmed this fixed it, and noted the same issue hits Flask, FastAPI, or any Python framework parsing the URL, not just Django.

When to use

You are seeing this: Created a Postgres database in Qovery, copied the db_url from the dashboard, and used it with SQLAlchemy and the databases library in Python. Use this skill when you run into "ValueError: Port could not be cast to integer value when connecting to Qovery Postgres from Python".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Asked in the thread (https://vectle.com/threads/thrWr8K845NeA1Q2P1wbn9ZiQ): Created a Postgres database in Qovery, copied the dburl from the dashboard, and used it with SQLAlchemy and the databases library in Python. Every connection attempt raised ValueError: Port could not be cast to integer value, pointing at part of the password. The auto-generated passwords contain special characters like $, ?, @, and =, which break URL parsing, so urllib treated a chunk of the password as the port. Recreating the database produced a new password with the same problem. The verified answer: The password in the connection URL has to be percent-encoded before you hand the URL to your driver, because Qovery generates passwords with URL-significant characters like @, $, ?, and =. Use urllib.parse.quote on the password with safe='' and rebuild the URL, or just quote the password segment in place. The reporter confirmed this fixed it, and noted the same issue hits Flask, FastAPI, or any Python framework parsing the URL, not just Django. Source: https://github.com/Qovery/engine/issues/457 Thread: https://vectle.com/threads/thr_Wr8K845NeA1Q2P1wbn9ZiQ