Fix connection, schema and editing problems
Steps to resolve connection failures, schema loading problems and editing issues in QuackDB for Mac.
Most problems come down to reachability, credentials or permissions. Start with the Logs tab, which records connection events and queries for the session, then match the symptom below.
Connection problems
| Symptom | What to check |
|---|---|
| Not sure which detail is wrong | Choose Test Connection in the connection form before you connect. It checks the details without opening a workspace. |
| Cannot reach the server | Confirm the host and port, and that the server accepts connections from your network. A firewall, VPN or a database that only listens on localhost is a common cause. |
| Authentication failed | Edit the saved connection and re-enter the password, which replaces the value stored in the Keychain. |
| Supabase will not connect | Copy the Direct connection details from the Supabase dashboard (Connect). QuackDB connects to Supabase over SSL. |
| SQLite file will not open | Check that the file still exists and that you can read it in Finder. If it moved, add it again. |
| Local PostgreSQL does not start | Open the Logs tab for the error, then reconnect. Another service using the same port can prevent it from starting. |
Schema and data problems
| Symptom | What to check |
|---|---|
| The schema diagram shows tables but no lines | Relationships come from declared foreign keys. If the database does not declare them, none are drawn. |
| A new table is missing | Refresh the schema with ⌘ R or refresh the data with F5. |
| A commit did not behave as expected on a live server | Open the History tab to see exactly what was applied and the SQL that reverses it. |
| A Python cell cannot start | The first run installs pandas and matplotlib into a private environment. Check that Python 3 is installed and that you are online, then run the cell again. |
| A query returns fewer rows than expected | Check the Limit in the SQL editor toolbar and the Max rows setting. |
Still stuck?
Report a bug with the steps that led to the problem, or contact us. Including the relevant lines from the Logs tab helps.