Get started guide

This guide shows how to get started with FluentJdbc in a project. ###Requirements### Java 8 ###Include FluentJdbc library###

<dependency>
    <groupId>org.codejargon</groupId>
    <artifactId>fluentjdbc</artifactId>
    <version>0.9.3</version>
</dependency>

###Set up FluentJdbc instance### A FluentJdbc instance is responsible for configuring FluentJdbc for a project and provides access to the Query API. The Query API needs access to JDBC Connections, provided by a ConnectionProvider. The following example shows this based on a JDBC DataSource.

DataSource dataSource = ...
ConnectionProvider provider = new DataSourceConnectionProvider(dataSource);
FluentJdbc fluentJdbc = new FluentJdbcBuilder()
	.connectionProvider(provider)
        // optional other configuration
	.build();

Note: There are many other ways than using a DataSource to integrate FluentJdbc to an environment. See further details at the Integration / ConnectionProvider section in the sidebar. ####Create a Query API instance#### With the configured ConnectionProvider

Query query = fluentJdbc.query();

Alternatively with a given Connection instance

Connection connection = ...
Query query = fluentJdbc.queryOn(connection);

The Query interface can then be used to execute SQL queries. ###Querying### Some examples: ####Update or insert queries#### Check Insert / Update page for detailed usage instructions. Some examples:

With positional parameters

UpdateResult result = query
	.update("UPDATE CUSTOMER SET NAME = ?, ADDRESS = ?")
	.params("John Doe", "Dallas")
	.run();

With named parameters

Map<String, Object> namedParams = new HashMap<>();
namedParams.put("name", "John Doe");
namedParams.put("address", "Dallas");

UpdateResult result = query
	.update("UPDATE CUSTOMER SET NAME = :name, ADDRESS = :address")
	.namedParams(namedParams)
	.run();

####Select queries##### Check the Select page for detailed usage details on select querying and result mapping. Some examples: #####List of results#####

List<Customer> customer = query
	.select("SELECT * FROM CUSTOMER WHERE NAME = ?")
	.params("John Doe")
	.listResult(resultSet -> new Customer(resultSet.getString("NAME")));

#####First result#####

Optional<Customer> firstCustomer = query
	.select("SELECT * FROM CUSTOMER WHERE NAME = ?")
	.params("John Doe")
	.firstResult(customerMapper);

#####Single result, convenience mappers#####

Map<String, Object> namedParams = ...
Long count = query
	.select("SELECT COUNT(*) FROM CUSTOMER WHERE NAME = :name")
	.namedParams(namedParams)
	.singleResult(Mappers.singleLong());

#####Iterating large resultsets#####

query
    .select("SELECT * FROM CUSTOMER")
    .iterateResult(customerMapper, (customer) -> {
        // do something with the customer
    });

####Batch inserts or updates#### Check Batch page for more usage details. Some examples:

With positional parameters:

Iterator<List<Object>> params = ...;
query
	.batch("INSERT INTO CUSTOMER(NAME, ADDRESS) VALUES(?, ?)")
	.params(params)
	.run();

With named parameters:

Iterator<Map<String, Object>> params = ...;
query
	.batch("INSERT INTO CUSTOMER(NAME, ADDRESS) VALUES(:name, :address)")
	.namedParams(params)
	.run();

####Custom parameter types#### Parameters can be normal JDBC types (Integer, Long, String, BigDecimal, java.sql.Date, ...) or java.time types - supported out of the box.

query
	.update("UPDATE CUSTOMER SET DEADLINE = ?, UPDATED = ?")
	.params(LocalDate.of(2015, Month.MARCH, 5), Instant.now())
	.run();

Support for more types can be configured. See Query parameter types page for more details

####Transactions#### Queries through the Query API are executed in transactions if the connections provided (either directly or by the ConnectionProvider implementation) are transaction managed. See Transactions section in the documentation for more details and examples.