class CQL::Postgres::Config

• CQL::Postgres::Config
• Reference
• Object

Overview

Everything needed to open a connection. The password never appears in #inspect, #to_s or error messages.

Query-string keys other than the ones listed here are sent to the server as startup parameters (?search_path=app). #user, #database, client_encoding and replication cannot be set that way, and libpq-only options the driver does not honour are rejected instead of ignored, so a typo can never silently weaken a connection. crystal-db's pool keys, which CQL.configure adds, are read too: max_pool_size and initial_pool_size as pool_size and pool_min_size, and the rest are ignored.

sslmode=prefer and require encrypt without verifying the server, like libpq, so sslrootcert is only accepted with verify-full, where it adds a CA to the system trust store (Crystal's TLS context cannot drop the system roots). Query values are percent-decoded only; + stays a plus.

Defined in:

Constant Summary

COMPAT_IGNORED_KEYS = {"auth_methods", "max_idle_pool_size", "retry_attempts", "retry_delay", "prepared_statements", "prepared_statements_cache"}

Accepted for configuration written for the pg shard or crystal-db's pool (CQL.configure emits both): this driver negotiates SCRAM/MD5 itself, and its pool has no idle cap, connect retries or unprepared mode.

CRYSTAL_DB_POOL_KEYS = {"max_pool_size" => "pool_size", "initial_pool_size" => "pool_min_size"}

crystal-db pool keys with an equivalent here; the native key wins when the URL names both.

DEFAULT_CONNECT_WAIT = 10.0

DRIVER_OPTION_KEYS = POOL_OPTION_KEYS + {"min_protocol_version", "max_protocol_version", "binary_params"}

POOL_OPTION_KEYS = {"pool_size", "pool_min_size", "checkout_timeout", "health_check_after", "max_queries", "max_idle_lifetime"}

RESERVED_PARAMETERS = {"user", "database", "dbname", "password", "hostaddr", "client_encoding", "replication"}

SCHEMES = {"postgres", "postgresql", "cockroachdb"}

UNSUPPORTED_LIBPQ = {"sslcert", "sslkey", "sslcrl", "sslcompression", "sslsni", "sslpassword", "channel_binding", "require_auth", "target_session_attrs", "passfile", "service", "gssencmode", "krbsrvname"}

Constructors

• .from_uri(uri : URI, user : String | Nil = uri.user.presence, password : String | Nil = uri.password, ignoring : Enumerable(String) = [] of String) : Config

  For callers that only hold a parsed URI (crystal-db's driver interface).

• .new(host : String = "localhost", port : Int32 = 5432, user : String = "postgres", password : Nil | String = nil, database : String | Nil = nil, ssl_mode : CQL::Postgres::SSLMode = SSLMode::Prefer, ssl_root_cert : Nil | String = nil, connect_timeout : Time::Span | Nil = DEFAULT_CONNECT_WAIT.seconds, application_name : String = "cql", statement_cache_size : Int32 = 256, startup_options : Hash(String, String) = {} of String => String, driver_options : Hash(String, String) = {} of String => String, cockroachdb : Bool = false)
• .parse(url : String) : Config

  Parses postgres://user:pass@host:5432/db?sslmode=require&application_name=app.

Class Method Summary

• .number(text : String | Nil, name : String) : Int32 | Nil
• .seconds(text : String | Nil, name : String) : Time::Span | Nil

  A positive or zero count of seconds (at most a year), or nil when absent.

• .whole(text : String | Nil, name : String) : Int64 | Nil

  A whole number that may not fit in 32 bits, or nil when absent.

Instance Method Summary

• #address : String

  Where the connection goes, for error messages.

• #application_name : String
• #binary_params? : Bool

  Send bind parameters in PostgreSQL's binary format where the server's parameter type has one (off by default; see the README).

• #cockroachdb? : Bool

  The URL said cockroachdb://.

• #connect_timeout : Time::Span | Nil

  How long each step of connecting and starting up may block (TCP connect, TLS, every server reply), not a total deadline; nil waits indefinitely.

• #database : String
• #driver_options : Hash(String, String)
• #host : String
• #inspect(io : IO) : Nil

  Appends a String representation of this object which includes its class name, its object address and the values of all instance variables.

• #max_protocol_version : ProtocolVersion
• #min_protocol_version : ProtocolVersion

  The protocol versions this connection may use.

• #password_for_authentication : String
• #port : Int32
• #socket_path : String
• #ssl_mode : SSLMode
• #ssl_root_cert : String | Nil
• #startup_options : Hash(String, String)
• #startup_parameters : Hash(String, String)
• #statement_cache_size : Int32
• #to_s(io : IO) : Nil

  Appends a short String representation of this object which includes its class name and its object address.

• #unix_socket? : Bool
• #user : String

Constructor Detail

Class Method Detail

Instance Method Detail

class Person
  def initialize(@name : String, @age : Int32)
  end
end

Person.new("John", 32).inspect # => #<Person:0x10fd31f20 @name="John", @age=32>

class Person
  def initialize(@name : String, @age : Int32)
  end
end

Person.new("John", 32).to_s # => #<Person:0x10a199f20>