#Postgres Client

#Quick Start

///|
async fn _quick_start() -> Unit {
  @async.with_task_group(group => {
    let config = @client.Config::Config(
      "localhost",
      user="postgres",
      database="app",
      password="secret",
      port=5432,
      ssl_mode=Disable,
      application_name="my-service",
    )
    let (client, executor) = @client.Client::create(config)
    let task = group.spawn(no_wait=true, () => executor.run())
    client.ready()
    let current_user : String = client
      .query_one("select current_user::text as current_user")
      .get_name("current_user")
    ignore(current_user)
    client.close()
    task.wait()
  })
}

#Execution Model

• prepare, type lookup, execute, and temporary-statement cleanup form one operation
• a row, simple-query, or COPY OUT stream owns the permit until EOF, finish(), or a detached background drain completes
• COPY IN owns it until finish() or abort()
• a transaction owns it until commit() or rollback()

#Query APIs

///|
async fn _query_example(client : @client.Client) -> Int32 {
  let input = 41
  let row = client.query_one("select $1::int4 + 1 as value", params=[
    input as &ToSql,
  ])
  row.get_name("value")
}

#Client Encoding

///|
async fn _first_value(client : @client.Client) -> Int32? {
  client.with_stream("select generate_series(1, 100) as value", stream => {
    match stream.next() {
      Some(row) => Some(row.get_name("value"))
      None => None
    }
  })
}

#Type Descriptors And Custom Arrays

///|
fn _accept_status(type_ : @client.Type) -> Bool {
  type_.schema == Some("app") && type_.name == "status" && type_.kind is Enum(_)
}

#Prepared Statements And Portals

///|
async fn _prepared_example(client : @client.Client) -> Int32 {
  client.with_prepared("select $1::int4 as value", statement => {
    let value = 7
    statement.with_stream(params=[value as &ToSql], stream => {
      let result : Int32 = stream.next().unwrap().get_name("value")
      result
    })
  })
}

///|
async fn _portal_example(client : @client.Client) -> Int32 {
  client.with_transaction(tx => {
    tx.with_prepared("select 7::int4 as value", statement => {
      statement.with_portal((portal : @client.Portal) => {
        portal.with_stream(1, stream => {
          let result : Int32 = stream.next().unwrap().get_name("value")
          result
        })
      })
    })
  })
}

///|
async fn _portal_pagination(client : @client.Client) -> Array[Int32] {
  let statement = client.prepare("select generate_series(1, $1::int4) as value")
  defer @async.protect_from_cancel(() => statement.close())
  client.with_transaction(tx => {
    tx.with_portal(statement, params=[3 as &ToSql], portal => {
      let values : Array[Int32] = []
      for ;; {
        let summary = portal.with_stream(2, stream => {
          for row in stream.collect() {
            values.push(row.get_name("value"))
          }
          stream.finish()
        })
        if !summary.suspended {
          break values
        }
      }
    })
  })
}

#Transactions

///|
async fn _transaction_example(client : @client.Client) -> Unit {
  client.with_transaction(tx => {
    ignore(tx.execute("update accounts set active = true"))
    ()
  })
}

///|
async fn _serializable_transaction(client : @client.Client) -> Unit {
  client.with_transaction(
    _tx => (),
    options=@client.TransactionOptions(
      isolation_level=@client.IsolationLevel::Serializable,
    ),
  )
}

///|
async fn _nested_transaction_example(client : @client.Client) -> Unit {
  client.with_transaction(tx => {
    tx.with_savepoint("optional_work", child => {
      child.with_stream("select 1", stream => ignore(stream.next()))
    })
  })
}

#COPY And Streams

///|
async fn _copy_rows(client : @client.Client) -> UInt64 {
  client.with_copy_in("copy events(value) from stdin", sink => {
    sink.send(b"first\nsecond\n")
    sink.finish()
  })
}

• RowStream, SimpleQueryStream, and CopyOutStream expose next, collect, finish, and detach as appropriate.
• CopyInSink::send feeds a bounded eight-chunk input queue; finish completes the copy and abort terminates it with an error.
• Dropping a handle is not a lifecycle operation. Explicitly finish, abort, or detach it.

#Async Messages

///|
async fn _read_async_message(client : @client.Client) -> @client.AsyncMessage? {
  client.next_message()
}

#Cancellation

#Configuration And TLS

• SslMode::Disable: plaintext
• SslMode::VerifyCa: TLS with certificate-chain validation
• SslMode::VerifyFull: TLS with certificate-chain and endpoint identity validation; this is the default

#Errors

///|
fn _is_email_conflict(error : Error) -> Bool {
  match error {
    @client.ClientError::Database(err) =>
      err.code == Some("23505") && err.constraint == Some("accounts_email_key")
    _ => false
  }
}