class: Jdbc

[30:14] (extern: com.lehman.aussomserver.connectors.Jdbc) extends: object

Jdbc class implements functionality for communicating with RDBMS systems using Java JDBC. The class is used by configuring the connection (driver, URL, credentials, optional driver properties), calling connect, and then issuing queries through select, selectMaps, selectEach, update, updateBatch, insertReturningKeys, execute, or call. Multi-statement work can be done inside a transaction by calling setAutoCommit(false), then commit() or rollback() at the end.

Methods

• setDriver (string Driver)

  Sets the JDBC driver with the provided driver string. This is the class name of the driver. An exampe is "com.mysql.cj.jdbc.Driver" for MySQL.

  • @p Driver is a string with the JDBC driver string.
  • @r this object.

• setUrl (string Url)

  Sets the server connection URL.

  • @p Url is a string with the server URL to connect to.
  • @r this object

• setUserName (string UserName)

  Sets the connection username.

  • @p UserName is a string with the connection username.
  • @r this object

• setPassword (string Password)

  Sets the connection password.

  • @p Password is a string with the connection password.
  • @r this object

• getDriver ()

  Gets the JDBC driver string.

  • @r A string with the JDBC driver.

• getUrl ()

  Gets the DB URL.

  • @r A string with the DB URL.

• getUserName ()

  Gets the DB user name.

  • @r A string with the DB user name.

• getPassword ()

  Gets the DB password.

  • @r A string with the DB password.

• setConnectionInfo (string Driver, string Url, string UserName, string Password)

  Sets all the connection information.

  • @p Driver is a string with the driver string.
  • @p Url is a string with the server URL.
  • @p UserName is a string with the connection username.
  • @p Password is a string with the connection password.
  • @r this object

• setProperty (string Key, string Value)

  Sets a driver-specific connection property that is forwarded to the JDBC driver at connect time. Common keys include sslmode, applicationName, currentSchema (Postgres), useSSL, serverTimezone (MySQL), and encrypt (SQL Server).

  • @p Key is the property name.
  • @p Value is the property value as a string.
  • @r this object.

• setProperties (map Props)

  Sets multiple driver-specific connection properties at once.

  • @p Props is a map of property name to string value.
  • @r this object.

• setLoginTimeout (int Seconds)

  Sets the connect timeout in seconds. The value is forwarded to the driver as the loginTimeout property; not all drivers honor this name. For drivers that use a different key (for example MySQL connectTimeout), call setProperty directly.

  • @p Seconds is an int with the connect timeout.
  • @r this object.

• setQueryTimeout (int Seconds)

  Sets a default per-statement query timeout in seconds. The value is applied to every PreparedStatement created by select, update, execute, and friends. A value of 0 disables the timeout.

  • @p Seconds is an int with the query timeout.
  • @r this object.

• setFetchSize (int Rows)

  Sets the JDBC fetch size hint applied to every statement. Drivers use this to decide how many rows to read from the server at a time, which is required for streaming large result sets. On Postgres the connection must also be in a transaction (setAutoCommit(false)) for fetch size to take effect.

  • @p Rows is an int with the fetch size.
  • @r this object.

• setAutoCommit (bool On)

  Turns auto-commit on or off. With auto-commit off, every statement runs inside a transaction that must be ended with commit() or rollback().

  • @p On is a bool. True turns auto-commit on, false turns it off.
  • @r this object.

• setReadOnly (bool On)

  Marks the connection as read-only as a hint to the driver. Some drivers route read-only connections to a replica.

  • @p On is a bool. True marks read-only, false marks read-write.
  • @r this object.

• connect ()

  Connects to the server.

  • @r this object.

• disconnect ()

  Disconnects from the server.

  • @r this object

• isConnected ()

  Returns whether a connection has been established. Note that this only checks the local handle; use isValid for a server-side liveness probe.

  • @r A bool, true if connected.

• isValid (int TimeoutSeconds = 5)

  Pings the database to check whether the connection is still usable. Most drivers send a lightweight server round-trip. Returns false if not connected or if the probe fails before the timeout elapses.

  • @p TimeoutSeconds is an int with the probe timeout. Default is 5.
  • @r A bool, true if the connection is valid.

• commit ()

  Commits the current transaction.

  • @r this object.

• rollback ()

  Rolls back the current transaction.

  • @r this object.

• select (string Query, list Params)

  Executes a select query with the provided query string and any params for the prepared statement. The returned map has a 'cols' key with column metadata and a 'rows' key with a list of rows. Each row is itself a list of values aligned to cols by position.

  • @p Query is a string with the query to execute.
  • @p Params is a list of params to use in the prepared statement.
  • @r A map with the query result in 'cols' and 'rows'.

• selectMaps (string Query, list Params)

  Performs a select query and returns rows as a list of maps keyed by column label. This is more ergonomic than select when you do not need column metadata.

  • @p Query is a string with the JDBC query.
  • @p Params is an optional list with prepared statement arguments.
  • @r A list of maps, one per row.

• selectEach (string Query, list Params, callback Cb)

  Performs a select query and invokes the provided callback once per row, streaming results without buffering them all in memory. The callback receives a single argument: a map representation of the row. If the callback returns false, iteration stops early.

  • @p Query is a string with the JDBC query.
  • @p Params is a list with prepared statement arguments.
  • @p Cb is a callback invoked once per row.
  • @r this object.

• update (string Query, list Params)

  Executes an update query with the provided query string and any params for the prepared statement.

  • @p Query is a string with the query to execute.
  • @p Params is a list of params to use in the prepared statement.
  • @r An int with the number of rows affected.

• updateBatch (string Query, list ParamRows)

  Performs the provided update query once per parameter row, sent to the driver as a single batch. Returns a list of row counts in the same order as ParamRows.

  • @p Query is a string with the JDBC query.
  • @p ParamRows is a list of parameter lists, one per batch row.
  • @r A list of ints with the per-row update counts.

• insertReturningKeys (string Query, list Params)

  Performs an insert and retrieves any auto-generated keys (identity / serial / sequence values) created by the insert. Returns a map with 'rowsAffected' and 'keys'. When the generated-keys result has a single column, 'keys' is a list of scalar values; otherwise it is a list of maps keyed by column label.

  • @p Query is a string with the JDBC insert query.
  • @p Params is an optional list with prepared statement arguments.
  • @r A map with 'rowsAffected' and 'keys'.

• execute (string Query, list Params)

  Executes any SQL statement. Use this for DDL like CREATE or DROP, or when the statement may or may not return a result set. The returned map has 'hasResultSet' (bool), 'updateCount' (int), and when hasResultSet is true also 'cols' and 'rows' just like select.

  • @p Query is a string with the SQL to run.
  • @p Params is an optional list with prepared statement arguments.
  • @r A map describing the result.

• call (string Sql, list Params)

  Calls a stored procedure or function. The Sql argument is the JDBC escape form, for example "{call my_proc(?, ?)}" or "{? = call my_func(?)}". Only IN parameters are supported through Params; for OUT parameters use a procedure that returns a result set instead. The returned map mirrors execute: 'hasResultSet', 'updateCount', and when applicable 'cols' and 'rows'.

  • @p Sql is the JDBC escape form for the call.
  • @p Params is an optional list of IN parameters.
  • @r A map describing the result.