How to Connect to a Database in VS Code (Explained Like You're New)

The Missing Piece: Client vs Server

Working with a database involves two separate programs:

• The database server stores the data and runs your queries. PostgreSQL, MySQL and SQL Server are servers. They run in the background, waiting for connections, usually on your own computer during learning.
• The client is where you type queries and see results. VS Code with SQLTools is a client. So are DBeaver, pgAdmin and TablePlus.

Think of the server as a phone at someone's house and the client as your phone. SQLTools can dial, but if there's no phone at the other end, or it's turned off, or you dialed the wrong number, the call fails.

So a connection needs four things: a running server, the right host (where it is, usually localhost), the right port (which "door," like 5432 for PostgreSQL), and a username and password the server will accept.

SQLite is the exception: it isn't a server at all. The whole database is a single file, and the client opens it directly. That's why it's the easiest place to start.

Option 1: SQLite (Easiest, No Server)

Best if you just want to practice queries today.

1. In VS Code, open the Extensions panel and install SQLTools.
2. Also install the driver extension SQLTools SQLite. SQLTools on its own can't talk to any database; each database needs its own driver extension. A missing driver is the most common reason connections fail.
3. The SQLite driver depends on Node.js. If you don't have it, install the LTS version from nodejs.org, then restart VS Code. When you first connect, SQLTools may offer to install the sqlite3 package; accept it.
4. Click the SQLTools icon in the sidebar, then Add New Connection, and choose SQLite.
5. Give it a name, and for Database File type a path like ./practice.db. If the file doesn't exist, it will be created.
6. Click Test Connection, then Save, then connect.

Open a new SQL file from the connection and run this to check everything works:

CREATE TABLE suspects (id INTEGER PRIMARY KEY, name TEXT, occupation TEXT);
INSERT INTO suspects (name, occupation) VALUES
  ('Mara Quinn', 'Dock manager'),
  ('Elias Grant', 'Accountant');
SELECT * FROM suspects;

If you see two rows, you're done. You have a working database.

Option 2: PostgreSQL Installed Locally (Most Realistic)

Best if you're learning for a data job. PostgreSQL is a real database server, the same kind you'll use at work.

Install and start the server

• Mac: install Postgres.app from postgresapp.com, open it, and click Initialize. It runs the server for you.
• Windows: download the installer from postgresql.org (the EDB installer). During setup it asks you to choose a password for the postgres user. Write it down. Keep the default port, 5432.
• Linux: install it with your package manager, for example sudo apt install postgresql.

Connect from VS Code

1. Install SQLTools and the SQLTools PostgreSQL/Cockroach Driver extension.
2. In SQLTools, choose Add New Connection and pick PostgreSQL.
3. Fill in: Server/Host localhost, Port 5432, Database postgres, Username postgres, and the password you chose. (Postgres.app's default username is your Mac username, with no password.)
4. Test the connection, save it and connect.

Option 3: PostgreSQL in Docker (Cleanest, If You Have Docker)

If you already use Docker, this starts a disposable server with one command:

docker run --name practice-pg -e POSTGRES_PASSWORD=secret -p 5432:5432 -d postgres:16

Then connect from SQLTools exactly as in Option 2, with username postgres and password secret. Stop it with docker stop practice-pg and start it again with docker start practice-pg. Your data stays until you remove the container.

Still Not Connecting? Check These in Order

1. Is the driver installed? SQLTools needs a separate driver extension per database. No driver, no connection type to choose.
2. Is the server actually running? Postgres.app shows a status; on Windows, look for the PostgreSQL service in Services; in Docker, run docker ps. "Connection refused" almost always means nothing is listening.
3. Right port? PostgreSQL defaults to 5432, MySQL to 3306, SQL Server to 1433. If you installed two Postgres versions, the second may be on 5433.
4. Right password? "Password authentication failed" means the server is running and you reached it, so you're close. Use the password from installation.
5. Does the database exist? Connect to the default database postgres first, then create your own with CREATE DATABASE practice;.
6. Read the actual error message. It almost always names the problem: refused (not running or wrong port), authentication failed (wrong user or password), or database does not exist.

"Connection refused" means nobody answered the phone. "Authentication failed" means someone answered but didn't recognize you. The second one is progress.

Not Tied to VS Code?

VS Code works, but dedicated database tools are often easier when you're starting out because they handle drivers for you. DBeaver (free, works with nearly every database) and pgAdmin (free, PostgreSQL only, included with the Windows installer) both let you browse tables and run queries with fewer setup steps.

Getting Some Data to Practice With

An empty database isn't much fun. Once you're connected, a few good sources of practice data:

• Sample databases such as the PostgreSQL "dvdrental" or "Pagila" datasets, and Chinook (available for SQLite, PostgreSQL and MySQL), which models a music store.
• CSV files from public data sites, imported with your client's import tool or PostgreSQL's \copy command.
• Your own tables: create a few small tables by hand, like the suspects example above. Small data you can check by eye is the best way to learn JOINs and GROUP BY.

Or Start Writing SQL Right Now

If setup is the thing standing between you and learning, skip it for now. SQL Side Quest's Learning Mode and Murder in Blackwater Bay run real queries against ready-made databases in your browser: no install, no connection settings, no account. Come back to the local setup once you're hooked.

• Not sure which database to install? MySQL vs PostgreSQL