If you’ve ever worked with Postgres, you’ve probably launched psql at least once. It’s the default database client packaged with the Postgres server. This is a command-line application, written in C, and it’s packed with many features such as autocompletion, command history, and data export/import.
psql is very popular in the Postgres community, and many developers use it daily. So, we decided to explore the possibility of running it in the browser.
Here’s the result—try it: https://psql.sh/
It all started in a hackathon…
This idea was born during one of our internal Neon hackathons. We occasionally hold these to explore new ideas in a fast, non-production environment without fear of breaking things.
After that, we were so enthusiastic about this idea that we decided to move forward and turn it into a real, working tool.
But we can’t just connect to the database from the browser, right?
Technically, that’s correct. Postgres relies on the TCP stack, which isn’t accessible from the browser environment. However, at Neon, we’ve deployed a WebSocket proxy that allows users to connect to their databases directly from browser-like environments. (Initially, we built this for serverless environments without TCP stack access, like Cloudflare Workers.)
We also developed a serverless driver to act as a client for the WebSocket proxy. It works great in many JavaScript environments—Node, Vercel Edge, Cloudflare Workers—and browsers!
So, when starting this project, we already had all the infrastructure in place; we just needed to emulate psql’s behavior in the browser.
What can the psql browser app do?
Our browser app instantiates a database from one of the chosen templates, so you can start with some data already present. Then, you get an almost instantaneous fresh connection spun up for you (I’ll explain how we achieve this in the next section).
You can write SQL queries that will be executed against this fresh database. This database is exclusive to you, so you can experiment with its data any way you like. You can also use slash commands to inspect the database schema, such as \d or \d <table-name>.
How we built it
Connection string
As mentioned, we use our serverless driver to connect to the database. But where do we get the connection string from?
For this, I created a Neon project with several branches—one for each template. So, the templates in psql.sh are actually Neon branches:
When someone instantiates a new connection, the backend simply creates a new child branch from the corresponding template (the main branch):
Since Neon branching is instantaneous, we can get a connection string right away. This connection string is also unique and isolated.
Slash commands
For slash commands, I used the same library we use in our Neon SQL Editor, created by George MacKerron. If you haven’t read about it, I highly recommend this blog post—it’s quite the journey!
Terminal emulation
For the terminal emulation, I considered xterm.js, but soon realized it would be an overkill for our needs. Our app doesn’t really emulate the terminal, only the psql session, which is a lot simpler. So, I created a terminal-like experience from scratch—which was quite fun.
For terminal emulation, I initially considered xterm.js, but I soon realized it would be overkill for our needs. Our app doesn’t emulate a full terminal; it only replicates the psql session, which is much simpler.
So, I built a terminal-like experience from scratch 🙂 and it was quite fun.
Next steps: Help us decide
We have plenty of ideas to improve the app experience (and sadly, so little spare time!)
- Would you like the ability to query your actual databases running in Neon or even elsewhere?
- How about AI-powered features like “SQL generation”?
Let us know your thoughts on Discord or in our GitHub discussions.
This project is also open-source, so feel free to explore the code and contribute directly: https://github.com/neondatabase-labs/psqlsh
