Connection

public final class Connection

Represents a connection to a PostgreSQL server

init/deinit

  • designated initializer.

    Declaration

    Swift

    public init(connectInfo: ConnectInfo)

    Parameters

    connectInfo

    the arguments that will be used to open a connection

  • Initializes with a fixed set of connection parameters

    Declaration

    Swift

    public convenience init(host: String = "localhost", port: String = "5432",
			user: String, password: String = "", dbname: String, sslMode:
	ConnectParam.SSLMode = .prefer)

    Parameters

    host

    the host to connect to. Defaults to localhost
    port

    The port to connect to, as a string. Defaults to 5432
    user

    the user to connect as
    password

    the password for user. Defauls to an empty string
    dbname

    the name of the ddatabase to connect to
    sslMode

    the SSL Mode to use. Defaults to .prefer

  • Creates a connection using the same parameters as the specified connection

    Declaration

    Swift

    public convenience init(cloning: Connection)

    Parameters

    cloning

    The connection to clone

open/close

  • opens the connection to the database server

    Declaration

    Swift

    public func open() throws

  • closes the connection to the database server

    Declaration

    Swift

    public func close()

status

  • the currently reported last error message from the server

    Declaration

    Swift

    public var lastErrorMessage: String { get }

  • true if the connection is currently open

    Declaration

    Swift

    public var isConnected: Bool { get }

  • Returns the version of the server. Only works if a connection is open.

    Declaration

    Swift

    public func serverVersion() throws -> String

    Return Value

    the server version string

transactions

  • Wraps a closure in a transaction. If an error is thrown, performs a rollback. Otherwise, performs a commit.

    Throws

    any errors executing the query

    Declaration

    Swift

    public func withTransaction<T>(body: (Connection) throws -> T?) throws -> T?

    Parameters

    body

    closure to execute. Passed the connection to use

    Return Value

    the value returned from the body closure

sql execution

  • Executes the query and returns the results

    Throws

    if connection isn’t open, or don’t get a valid response

    Declaration

    Swift

    @discardableResult
public func execute(query: String) throws -> PGResult

    Parameters

    query

    query to perform

    Return Value

    the results of that query

  • Execute a query with parameters

    Throws

    if connection not open, don’t get a valid response, query parameter mismatch

    Declaration

    Swift

    @discardableResult
public func execute(query: String, parameters: [QueryParameter?]) throws -> PGResult

    Parameters

    query

    the query string with placeholders ($1,$2, etc.) for each parameter
    parameters

    array of QueryParameters

    Return Value

    the results of the query

  • Execute the query and returns the results. Internally transfers data in binary format

    Throws

    if connection isn’t open, or don’t get a valid response

    Declaration

    Swift

    @discardableResult
public func executeBinary(query: String) throws -> PGResult

    Parameters

    query

    query to perform

    Return Value

    the results of that query

  • Returns the value of row 0, column 0 of a query that returns 1 row and 1 column

    Throws

    if the data types don’t match, or an error executing query

    Declaration

    Swift

    public func getSingleRowValue<T>(query: String) throws -> T?

    Parameters

    query

    a query that should return 1 row with 1 column

    Return Value

    the value

Notify/Listen

  • Creates a dispatch read source for this connection that will call callback on queue when a notification is received

    Throws

    if fails to get the socket for the connection

    Declaration

    Swift

    public func listen(toChannel channel: String, queue: DispatchQueue, callback: @escaping (_ notification: PGNotification?, _ error: Error?) -> Void) throws -> DispatchSourceRead

    Parameters

    channel

    the channel to register for
    queue

    the queue to create the DispatchSource on
    callback

    the callback
    notification

    The notification received from the database
    error

    Any error while reading the notification. If not nil, the source will have been canceled

    Return Value

    the dispatch socket to activate