com.github.susom.database

Interface Database

All Superinterfaces:

javax.inject.Provider<Database>, java.util.function.Supplier<Database>

All Known Implementing Classes:

DatabaseImpl

public interface Database
extends javax.inject.Provider<Database>, java.util.function.Supplier<Database>

Primary class for accessing a relational (SQL) database.

Author:

garricko

Method Summary

Modifier and Type	Method and Description
void	assertTimeSynchronized() Convenience method, same as assertTimeSynchronized(long, long) with millisToWarn=10000 and millisToError=30000.
void	assertTimeSynchronized(long millisToWarn, long millisToError) Check the JVM time (and timezone) against the database and log a warning or throw an error if they are too far apart.
void	commitNow() Cause the underlying connection to commit its transaction immediately.
Ddl	ddl(String sql) Create a DDL (schema modifying) statement for further manipulation and execution.
void	dropSequenceQuietly(String sequenceName) Convenience method to deal with mutually incompatible syntax for this.
void	dropTableQuietly(String tableName) Convenience method to deal with dropping tables that may or may not exist.
Flavor	flavor() Access information about what kind of database we are dealing with.
Long	nextSequenceValue(String sequenceName) Read the next value from a sequence.
Date	nowPerApp() Get the value that would be used if you specify an argNowPerApp() parameter.
Options	options()
void	rollbackNow() Cause the underlying connection to roll back its transaction immediately.
SqlUpdate	toDelete(Sql sql)
SqlUpdate	toDelete(String sql) Create a SQL "delete" statement for further manipulation and execution.
SqlInsert	toInsert(Sql sql)
SqlInsert	toInsert(String sql) Create a SQL "insert" statement for further manipulation and execution.
SqlSelect	toSelect(Sql sql)
SqlSelect	toSelect(String sql) Create a SQL "select" statement for further manipulation and execution.
SqlUpdate	toUpdate(Sql sql)
SqlUpdate	toUpdate(String sql) Create a SQL "update" statement for further manipulation and execution.
Connection	underlyingConnection() Obtain direct access to the connection being used by this instance.
When	when() A little syntax sugar to make it easier to customize your SQL based on the specific database.

Methods inherited from interface javax.inject.Provider

get

Methods inherited from interface java.util.function.Supplier

get

Method Detail

toInsert

@Nonnull
 @CheckReturnValue
SqlInsert toInsert(@Syntax(value="SQL") @Nonnull
                                               String sql)

Create a SQL "insert" statement for further manipulation and execution. Note this call does not actually execute the SQL.

Parameters:

sql - the SQL to execute, optionally containing indexed ("?") or named (":foo") parameters. To include the characters '?' or ':' in the SQL you must escape them with two ("??" or "::"). You MUST be careful not to pass untrusted strings in as SQL, since this will be executed in the database.

Returns:

an interface for further manipulating the statement; never null

toInsert

@Nonnull
 @CheckReturnValue
SqlInsert toInsert(@Nonnull
                                               Sql sql)

toSelect

@Nonnull
 @CheckReturnValue
SqlSelect toSelect(@Syntax(value="SQL") @Nonnull
                                               String sql)

Create a SQL "select" statement for further manipulation and execution. Note this call does not actually execute the SQL.

Parameters:

sql - the SQL to execute, optionally containing indexed ("?") or named (":foo") parameters. To include the characters '?' or ':' in the SQL you must escape them with two ("??" or "::"). You MUST be careful not to pass untrusted strings in as SQL, since this will be executed in the database.

Returns:

an interface for further manipulating the statement; never null

toSelect

@Nonnull
 @CheckReturnValue
SqlSelect toSelect(@Nonnull
                                               Sql sql)

toUpdate

@Nonnull
 @CheckReturnValue
SqlUpdate toUpdate(@Syntax(value="SQL") @Nonnull
                                               String sql)

Create a SQL "update" statement for further manipulation and execution. Note this call does not actually execute the SQL.

Parameters:

sql - the SQL to execute, optionally containing indexed ("?") or named (":foo") parameters. To include the characters '?' or ':' in the SQL you must escape them with two ("??" or "::"). You MUST be careful not to pass untrusted strings in as SQL, since this will be executed in the database.

Returns:

an interface for further manipulating the statement; never null

toUpdate

@Nonnull
 @CheckReturnValue
SqlUpdate toUpdate(@Nonnull
                                               Sql sql)

toDelete

@Nonnull
 @CheckReturnValue
SqlUpdate toDelete(@Syntax(value="SQL") @Nonnull
                                               String sql)

Create a SQL "delete" statement for further manipulation and execution. Note this call does not actually execute the SQL.

Parameters:

sql - the SQL to execute, optionally containing indexed ("?") or named (":foo") parameters. To include the characters '?' or ':' in the SQL you must escape them with two ("??" or "::"). You MUST be careful not to pass untrusted strings in as SQL, since this will be executed in the database.

Returns:

an interface for further manipulating the statement; never null

toDelete

@Nonnull
 @CheckReturnValue
SqlUpdate toDelete(@Nonnull
                                               Sql sql)

ddl

@Nonnull
 @CheckReturnValue
Ddl ddl(@Syntax(value="SQL") @Nonnull
                                    String sql)

Create a DDL (schema modifying) statement for further manipulation and execution. Note this call does not actually execute the SQL.

Parameters:

sql - the SQL to execute, optionally containing indexed ("?") or named (":foo") parameters. To include the characters '?' or ':' in the SQL you must escape them with two ("??" or "::"). You MUST be careful not to pass untrusted strings in as SQL, since this will be executed in the database.

Returns:

an interface for further manipulating the statement; never null

nextSequenceValue

@CheckReturnValue
Long nextSequenceValue(@Nonnull
                                         String sequenceName)

Read the next value from a sequence. This method helps smooth over the syntax differences across databases.

nowPerApp

Date nowPerApp()

Get the value that would be used if you specify an argNowPerApp() parameter.

commitNow

void commitNow()

Cause the underlying connection to commit its transaction immediately. This must be explicitly enabled (see Options, or it will throw a DatabaseException.

rollbackNow

void rollbackNow()

Cause the underlying connection to roll back its transaction immediately. This must be explicitly enabled (see Options, or it will throw a DatabaseException.

underlyingConnection

@Nonnull
Connection underlyingConnection()

Obtain direct access to the connection being used by this instance. Be very careful as this is highly likely to be unsafe and cause you great pain and suffering. This method is included to help ease into the library in large codebases where some parts still rely on direct JDBC access.

By default this method will throw a DatabaseException. If you want to use this method you must explicitly enable it via Options.allowConnectionAccess()

options

@Nonnull
Options options()

flavor

@Nonnull
Flavor flavor()

Access information about what kind of database we are dealing with.

when

@Nonnull
When when()

A little syntax sugar to make it easier to customize your SQL based on the specific database. For example:

"select 1" + db.when().oracle(" from dual")

"select " + db.when().postgres("date_trunc('day',").other("trunc(") + ") ..."

Returns:

an interface for chaining or terminating the conditionals

dropSequenceQuietly

void dropSequenceQuietly(String sequenceName)

Convenience method to deal with mutually incompatible syntax for this. For example:

Oracle: 'drop sequence x'

Derby: 'drop sequence x restrict'

"

dropTableQuietly

void dropTableQuietly(String tableName)

Convenience method to deal with dropping tables that may or may not exist. Some databases make it hard to check and conditionally drop things, so we will just try to drop it and ignore the errors.

Parameters:

tableName - the table to be dropped

assertTimeSynchronized

void assertTimeSynchronized(long millisToWarn,
                            long millisToError)

Check the JVM time (and timezone) against the database and log a warning or throw an error if they are too far apart. It is a good idea to do this before you store and dates, and maybe make it part of your health checks. If the clocks differ by more than an hour, a DatabaseException is thrown suggesting you check the timezones (under the assumptions the JVM and database are running in different timezones).

Parameters:

millisToWarn - if the clocks disagree by more than this and less than millisToError, a warning will be dropped in the log

millisToError - if the clocks disagree by more than this a DatabaseEception will be thrown

assertTimeSynchronized

void assertTimeSynchronized()

Convenience method, same as assertTimeSynchronized(long, long) with millisToWarn=10000 and millisToError=30000.