Getting Started

Installation

Add Volt to your project using your preferred build tool:

Gradle (Kotlin)

dependencies {
    implementation("io.github.oskarscot:volt-core:0.0.3")
}

Gradle (Groovy)

dependencies {
    implementation 'io.github.oskarscot:volt-core:0.0.3'
}

Maven

<dependency>
    <groupId>io.github.oskarscot</groupId>
    <artifactId>volt-core</artifactId>
    <version>0.0.3</version>
</dependency>

Requirements

• Java 21 or later
• PostgreSQL database

Basic Setup

1. Define an Entity

Create a class annotated with @Entity to map to a database table:

import me.oskarscot.volt.annotation.Entity;
import me.oskarscot.volt.annotation.Identifier;
import me.oskarscot.volt.annotation.NamedField;
import me.oskarscot.volt.entity.PrimaryKeyType;

@Entity("users")
public class User {

    @Identifier(type = PrimaryKeyType.NUMBER, generated = true)
    private Long id;

    @NamedField(name = "user_name")
    private String username;

    private String email;

    public User() {}

    // Getters and setters
}

2. Create a Volt Instance

Volt uses HikariCP for connection pooling. Configure and create your instance using VoltFactory:

import com.zaxxer.hikari.HikariConfig;
import me.oskarscot.volt.Volt;
import me.oskarscot.volt.VoltFactory;

HikariConfig config = new HikariConfig();
config.setJdbcUrl("jdbc:postgresql://localhost:5432/mydb");
config.setUsername("postgres");
config.setPassword("password");

Volt volt = VoltFactory.createVolt(config);

3. Register Entities

Register your entity classes before performing operations:

volt.registerEntity(User.class);

4. Test the Connection

Verify your database connection:

if (volt.testConnection()) {
    System.out.println("Connected to database!");
}

The Result Type

Volt uses a Result<T, VoltError> type for all operations instead of throwing exceptions. Inspired by Rust's Result, this provides explicit error handling.

Result<User, VoltError> result = volt.findById(User.class, 1L);

if (result.isSuccess()) {
    User user = result.getValue();
    System.out.println("Found: " + user.getUsername());
} else {
    VoltError error = result.getError();
    System.out.println("Error: " + error.getMessage());
}

Result Methods

Method	Description
isSuccess()	Returns true if the operation succeeded
isFailure()	Returns true if the operation failed
getValue()	Returns the success value (throws if failed)
getError()	Returns the error (throws if succeeded)

Creating Results

When building your own methods that integrate with Volt:

// Success
Result.okay(value)

// Failure
Result.failure(new VoltError("Something went wrong"))

Perform Operations

Volt provides convenient methods for simple operations. All methods return Result<T, VoltError>:

// Save (insert or upsert)
User user = new User();
user.setUsername("john");
user.setEmail("john@example.com");

Result<User, VoltError> saveResult = volt.save(user);
if (saveResult.isSuccess()) {
    User saved = saveResult.getValue();
    System.out.println("Saved user with ID: " + saved.getId());
}

// Find by ID
Result<User, VoltError> findResult = volt.findById(User.class, 1L);
if (findResult.isSuccess()) {
    User found = findResult.getValue();
}

// Delete
Result<Void, VoltError> deleteResult = volt.delete(user);

For more complex operations, use transactions:

try (Transaction tx = volt.beginTransaction()) {
    Result<List<User>, VoltError> result = tx.findAll(User.class);
    // ... more operations
    tx.commit();
}

Next Steps

• Learn about Entities and annotations
• Explore the Query Builder for complex queries
• Understand Transactions for atomic operations
• Create Custom Converters for your types