connect

Arguments: &key host port user file password database external-format client-flags

The arguments are:

• host: a string naming the machine to connect to, or a list with the first element being a string naming the host to connect to followed any number of keyword arguments accepted by socket:make-ssl-client-stream These arguments will be passed to socket:make-ssl-client-stream when negotiating an SSL connection if CLIENT_SSL is included in the client-flag argument documented below, and are otherwise ignored. host defaults to "localhost".
• port: an integer specifying the port to connect to. Defaults to 3306.
• user: a string providing a user name to send to authenticate. Defaults to the current user's login name.
• file: the value can be either a pathname designator which can be used in place of host and port to specify the Unix-domain socket on which mysql is listening for a connection; or any other non-nil value. If a non-nil value which is not a pathname designator, the system connects to "/var/lib/mysql/mysql.sock" which is the default Unix-domain socket used by mysql on Linux (and perhaps other architectures as well). This argument can only be used if both the client and server are running the same Unix machine.
• password: if given, then password to send.
• database: if given, then initial database to use.
• external-format: the value can be nil, a symbol or string naming an external format, or an external format object. This argument sets the external-format used to process strings for this connection. If external-format is nil then no external format processing is done (nil is equivalent to the :octets external format except that nil is faster since the external-format processing code is bypassed). External formats are described in iacl.htm.
• client-flags: if supplied, should be a bitmask of flags indicating the capabilities of the mysql client. Any specified flags are logior'd with the default capabilities of the mysql client. See the MySQL documentation for the server version you are using for the available capability flags. Many of the common flags have been exported from the dbi.mysql package for ease of use (e.g. dbi.mysql:CLIENT_FOUND_ROWS).

Connects to the mysql database, authenticates the user and optionally sets the current database.

The instance of mysql to which to connect is specified by either the file argument or the host and port arguments. If both the client and server are running the same Unix machine then the file argument can be used to specify the Unix-domain socket on which mysql is listening for a connection. Typically that socket is named "/var/lib/mysql/mysql.sock".

If a file argument isn't given to connect then the host and port arguments specify the location of the mysql server. By default the host argument has value "localhost" (meaning the same machine as the client) and the port argument has the value 3306 (which is the normal port on which mysql listens).

Once connected to the mysql server the connect function will then pass the user and password to the mysql server so that it can authenticate the client. The rules for authentication are described in great detail in the MySQL reference manual (available on the http://www.mysql.com website, whose main page refers to it as the MySQL Manual). The default value for the user argument is the user's login name (the value returned by user-name). The password for an account is given in the mysql.user table of the mysql database. This password is unrelated to the password used to log onto the machine. If the database argument is given then once authentication succeeds, the connect makes the given database the current database.

connect returns a mysql object which can be used as the value of the db argument in calls to other functions in this library. connect also sets the value of the symbol *mysql* to the mysql object being returned. Since *mysql* is the default value for the db argument in other functions in this library, this means that if you're just experimenting with mysql interactively, you can call connect and then other functions in this library without saving the mysql object returned by connect and then passing it back in subsequent calls.

See mysql.htm for information on the Allegro MySQL facility.

Copyright (c) 1998-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page was not revised from the 10.0 page.
Created 2019.8.20.