Syntax

Dial-return

The connection object returned by Dial. WebSocket (ws, wss), TCP (tcp, tls) and database connections all return this object; database connections also have exec(). When the connection fails, Dial() returns a null value and logs an error (Rust returns a connection object whose Valid() is false).

Attributes

Name	Type	Description
read(timeout)	function	Reads one message. `timeout` is in milliseconds: without it the call blocks until data arrives; a positive value is the maximum wait, returning a null value on timeout. Two values apply to WebSocket only: `-1` does not wait and returns a null value at once if there is no data; `-2` does not wait and returns only the newest message, discarding older ones in the buffer.
write(data)	function	Sends data and returns the number of bytes sent; `0` when the connection is closed.
close()	function	Closes the connection. A WebSocket connection with automatic reconnection (`reconnect=true` in the address) is reconnected by the runtime and need not be closed; a closed connection cannot be used again.
exec(sql, ...args)	function	Database connections only: executes an SQL statement; usage and return value as `DBExec` (see `DBExec-return`). In `JavaScript` and `Python` the values for `?` placeholders can follow the SQL statement.
fd()	function	`JavaScript` only: returns a handle to the same connection. Pass the handle to another thread (for example as an argument of `threading.Thread()`) and call `Dial(handle)` there to get a connection object for the same connection; works for WebSocket, TCP and database connections. The handle's `valueOf()` is the connection number.
Valid()	function	`Rust` only: whether the connection was established.

See Also

Dial DBExec EventLoop

Remarks

In JavaScript a database connection object itself can also be passed to a thread created by threading.Thread(), stored in threading.Dict() or sent to another thread with postMessage(), sharing one connection between threads; the connection is closed automatically when the object is no longer referenced. Python and Rust cannot share connections between threads.

The receive buffer of read() and its behavior for each timeout:

Data received over WebSocket goes into a receive buffer (a queue) and accumulates when read() calls are far apart; by default the buffer holds at most 4096 messages or 16 MB (whichever comes first) and drops the oldest data beyond that. The limits can be changed with qsize and qbytes in the Dial() address.

Situation	No argument	-1	-2	2000 (ms)
Buffer has data	Returns the oldest data at once	Returns the oldest data at once	Returns the newest data at once, discarding the rest	Returns the oldest data at once
Buffer is empty	Blocks until data arrives	Returns a null value at once	Returns a null value at once	Waits at most 2000 ms; null value if no data
Connection closed or reconnecting	Returns an empty string `""`	--	--	--