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#### All queries executed through the query API rely on Connections provided by the ConnectionProvider being transaction-managed if necessary. Check the Transactions page for further details.