Environment Setup

Before you can write JDBC code, you need three things: a running database, a way to talk to it, and the JDBC driver inside your Java project. This chapter explains supported databases, points you to the right MySQL installation guide for your OS, and shows how to add the JDBC driver to a Maven project.

Prerequisites

• JDK 21 installed
• Basic command line familiarity
• Administrator access (for some installation methods)

Supported Databases

JDBC is not tied to a single database. Any relational database that ships a JDBC driver can be accessed through the same API. The popular choices include:

This tutorial uses MySQL 8 for all examples. MySQL is open source, widely documented, and matches the SQL dialect you are most likely to encounter in commercial Java projects. The JDBC concepts you learn here transfer directly to PostgreSQL, H2, or any other database — only the connection URL and driver dependency change.

Installing MySQL

Choose one guide below. Each chapter ends with the same jdbc_demo database and jdbc_user account used in later lessons.

Creating a Test Database

Once MySQL is running, create a dedicated database and user for this tutorial:

-- Create the tutorial database
CREATE DATABASE jdbc_demo CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
 
-- Create a user for the tutorial
CREATE USER 'jdbc_user'@'%' IDENTIFIED BY 'jdbcpass';
 
-- Grant privileges on the demo database
GRANT ALL PRIVILEGES ON jdbc_demo.* TO 'jdbc_user'@'%';
 
-- Apply changes
FLUSH PRIVILEGES;

From now on, use jdbc_user / jdbcpass in your Java connection strings instead of the root account. This follows the principle of least privilege.

MySQL Client Tools

You can interact with MySQL through the command line, but a graphical client makes exploring schemas and testing queries much easier.

This tutorial recommends DBeaver Community Edition. It is free, open source, runs everywhere, and supports dozens of databases beyond MySQL. Download it from dbeaver.io, create a new connection to localhost:3306, and log in with jdbc_user / jdbcpass.

Preparing the JDBC Driver

With the database running, the next step is making the MySQL JDBC driver available to your Java project.

Adding the Dependency

Open your pom.xml and add the MySQL Connector/J driver:

<dependencies>
    <!-- MySQL JDBC driver -->
    <dependency>
        <groupId>com.mysql</groupId>
        <artifactId>mysql-connector-j</artifactId>
        <version>8.3.0</version>
    </dependency>
</dependencies>

Save the file and reload the Maven project. Maven downloads the driver and its transitive dependencies into ~/.m2/repository.

How Driver Loading Works

In older JDBC tutorials, you will see this line:

// Historical way to load a JDBC driver (no longer needed)
Class.forName("com.mysql.cj.jdbc.Driver");

Since JDBC 4.0 (Java 6), this is unnecessary. The driver JAR contains a META-INF/services/java.sql.Driver file that tells Java's ServiceLoader mechanism to register the driver automatically. As long as the driver is on the classpath, DriverManager.getConnection() finds it without any explicit loading code.

You can verify the driver is present by checking the dependency tree:

# List the MySQL driver in the dependency tree
mvn dependency:tree | grep mysql

You should see mysql-connector-j in the output.

Verifying the Full Setup

Create a minimal Maven project or reuse the one from the Maven tutorial. Add the MySQL dependency above. Then create a quick verification class:

Run it with:

mvn compile exec:java -Dexec.mainClass="com.example.SetupCheck"

If you see Connection valid: true, everything is wired up correctly. If not, check the error message against the FAQ below.

FAQ

Do I have to use MySQL? Can I follow along with PostgreSQL or H2?

Absolutely. The JDBC API is identical across databases. Change the dependency to org.postgresql:postgresql or com.h2database:h2, adjust the connection URL, and everything else in this tutorial works the same.

What is the difference between mysql-connector-java and mysql-connector-j?

mysql-connector-j is the new Maven coordinate for MySQL Connector/J starting with version 8.0.31. The old mysql:mysql-connector-java coordinate is deprecated. Use com.mysql:mysql-connector-j for new projects.

Why does my connection fail with "Access denied"?

Either the username or password is wrong, or the user does not have permission to connect from your host. If you are connecting from outside Docker, make sure the MySQL user was created with 'user'@'%' (any host) rather than 'user'@'localhost' (local socket only).

How do I completely reset my Docker MySQL container?

# Stop and remove the container
docker stop jdbc-mysql && docker rm jdbc-mysql
 
# Start a fresh one
docker run -d --name jdbc-mysql -p 3306:3306 -e MYSQL_ROOT_PASSWORD=rootpass mysql:8

All data in the old container is gone. If you need persistence across restarts, add a Docker volume:

docker run -d --name jdbc-mysql -p 3306:3306 \
  -e MYSQL_ROOT_PASSWORD=rootpass \
  -v mysql-data:/var/lib/mysql \
  mysql:8

Do I need to install Maven separately for JDBC projects?

Yes. JDBC code is plain Java, but managing the MySQL driver dependency through Maven is far easier than downloading JARs manually. If you do not have Maven installed, revisit the Maven installation chapter in this series.