drivers / all drivers should use the same parameters for the connection string

[gionatamettifogo]

We should have one type of connection string and it should work across devices. Doesn't really matter what the names are too much, but they should be the same in Javascript, core library, python and what not. I propose the format below. Let's discuss below...

Plus feature: Humans aren't perfect, so let make all options work regarless of case if we can, eg.:
sqlitecloud://host.sqlite.cloud:8860apiKey=xxx
sqlitecloud://host.sqlite.cloud:8860apikey=xxx

/** Configuration for SQLite cloud connection */
export interface SQLiteCloudConfig {
  /** Connection string in the form of sqlitecloud://user:password@host:port/database?options */
  connectionString?: string

  /** User name is required unless connectionString is provided */
  username?: string
  /** Password is required unless connection string is provided */
  password?: string
  /** True if password is hashed, default is false */
  passwordHashed?: boolean
  /** API key can be provided instead of username and password */
  apiKey?: string

  /** Host name is required unless connectionString is provided, eg: xxx.sqlitecloud.io */
  host?: string
  /** Port number for tls socket */
  port?: number
  /** Connect using plain TCP port, without TLS encryption, NOT RECOMMENDED, TEST ONLY */
  insecure?: boolean

  /** Optional query timeout passed directly to TLS socket */
  timeout?: number
  /** Name of database to open */
  database?: string

  /** Create the database if it doesn't exist? */
  createDatabase?: boolean
  /** Database will be created in memory */
  dbMemory?: boolean
  /* Enable compression */
  compression?: boolean
  /** Request for immediate responses from the server node without waiting for linerizability guarantees */
  nonlinearizable?: boolean
  /** Server should send BLOB columns */
  noBlob?: boolean
  /** Do not send columns with more than max_data bytes */
  maxData?: number
  /** Server should chunk responses with more than maxRows */
  maxRows?: number
  /** Server should limit total number of rows in a set to maxRowset */
  maxRowset?: number

  /** Custom options and configurations for tls socket, eg: additional certificates */
  tlsOptions?: tls.ConnectionOptions

  /** True if we should force use of SQLite Cloud Gateway and websocket connections, default: true in browsers, false in node.js */
  useWebsocket?: boolean
  /** Url where we can connect to a SQLite Cloud Gateway that has a socket.io deamon waiting to connect, eg. wss://host:4000 */
  gatewayUrl?: string

  /** Optional identifier used for verbose logging */
  clientId?: string
  /** True if connection should enable debug logs */
  verbose?: boolean
}

[gionatamettifogo]

Also, should we make these compatible with the various SDKs for each language? eg. js sqlite3, python etc?

[gionatamettifogo]

related issue:
https://github.com/orgs/sqlitecloud/projects/1/views/2?pane=issue&itemId=59485628

[marcobambini]

The single source of truth must be the C SDK used by the core server and all the other SDKs (except JS).

A connection string is in the form:
sqlitecloud://user:pass@host.com:port/dbname?timeout=10&key2=value2&key3=value3

The following keys are currently supported:

• timeout: (integer >= 0) client connection timeout parameter (in seconds)
  • client socket option
• compression: (1 or 0) set if client supports LZ4 compression
  • SET CLIENT KEY COMPRESSION TO 1;
• zerotext: (1 or 0) flag to tell the server to zero-terminate strings
  • SET CLIENT KEY ZEROTEXT TO 1;
• memory: (1 or 0) flag to force the database to be in-memory
  • database name is set to :memory:
• create: (1 or 0) flag to force the creation of the database (if it does not exist)
  • database name is used in CREATE DATABASE dbname IF NOT EXISTS
• insecure: (1 or 0) flag to disable TLS
  • client socket option
• non_linearizable: (1 or 0) flag to request for immediate responses from the server node without waiting for linerizability guarantees
  • SET CLIENT KEY NONLINEARIZABLE TO 1;
• no_verify_certificate: (1 or 0) flag to accept invalid TLS certificates
  • client socket option
• root_certificate: (string) full path to TLS root certificate
  • client socket option
• client_certificate: (string) full path to TLS client certificate
  • client socket option
• client_certificate_key: (string) full path to TLS client certificate key
  • client socket option
• noblob: (1 or 0) flag to tell the server to not send BLOB columns in rowsets
  • SET CLIENT KEY NOBLOB TO 1;
• maxdata: (integer >= 0) value to tell the server to not send columns with more than max_data bytes
  • SET CLIENT KEY MAXDATA TO 1;
• maxrows: (integer >= 0) value to control rowset chunks based on the number of rows
  • SET CLIENT KEY MAXROWS TO 1;
• maxrowset: (integer >= 0) value to control the maximum allowed size for a rowset
  • SET CLIENT KEY MAXROWSET TO 1;
• apikey: (string) apikey value used for authentication (instead of username/password)
  • AUTH APIKEY value;

[gionatamettifogo]

Why non_linearizable (with _) but then noblob (oneword) or maxrowset?

[gionatamettifogo]

/**
 * Configuration for SQLite cloud connection
 * @note Options are all lowecase so they 1:1 compatible with C SDK
 */
export interface SQLiteCloudConfig {
  /** Connection string in the form of sqlitecloud://user:password@host:port/database?options */
  connectionstring?: string

  /** User name is required unless connectionstring is provided */
  username?: string
  /** Password is required unless connection string is provided */
  password?: string
  /** True if password is hashed, default is false */
  password_hashed?: boolean
  /** API key can be provided instead of username and password */
  apikey?: string

  /** Host name is required unless connectionstring is provided, eg: xxx.sqlitecloud.io */
  host?: string
  /** Port number for tls socket */
  port?: number
  /** Connect using plain TCP port, without TLS encryption, NOT RECOMMENDED, TEST ONLY */
  insecure?: boolean

  /** Optional query timeout passed directly to TLS socket */
  timeout?: number
  /** Name of database to open */
  database?: string

  /** Create the database if it doesn't exist? */
  create?: boolean
  /** Database will be created in memory */
  memory?: boolean
  /* Enable compression */
  compression?: boolean
  /** Request for immediate responses from the server node without waiting for linerizability guarantees */
  non_linearizable?: boolean
  /** Server should send BLOB columns */
  noblob?: boolean
  /** Do not send columns with more than max_data bytes */
  maxdata?: number
  /** Server should chunk responses with more than maxRows */
  maxrows?: number
  /** Server should limit total number of rows in a set to maxRowset */
  maxrowset?: number

  /** Custom options and configurations for tls socket, eg: additional certificates */
  tlsoptions?: tls.ConnectionOptions

  /** True if we should force use of SQLite Cloud Gateway and websocket connections, default: true in browsers, false in node.js */
  usewebsocket?: boolean
  /** Url where we can connect to a SQLite Cloud Gateway that has a socket.io deamon waiting to connect, eg. wss://host:4000 */
  gatewayurl?: string

  /** Optional identifier used for verbose logging */
  clientid?: string
  /** True if connection should enable debug logs */
  verbose?: boolean
}