begriffs open source - ai-pg/blob - full-docs/txt/ecpg-sql-connect.txt

   1
   2 CONNECT
   3
   4    CONNECT — establish a database connection
   5
   6 Synopsis
   7
   8 CONNECT TO connection_target [ AS connection_name ] [ USER connection_user ]
   9 CONNECT TO DEFAULT
  10 CONNECT connection_user
  11 DATABASE connection_target
  12
  13 Description
  14
  15    The CONNECT command establishes a connection between the client and the
  16    PostgreSQL server.
  17
  18 Parameters
  19
  20    connection_target #
  21           connection_target specifies the target server of the connection
  22           on one of several forms.
  23
  24         [ database_name ] [ @host ] [ :port ] #
  25                 Connect over TCP/IP
  26
  27         unix:postgresql://host [ :port ] / [ database_name ] [
  28                 ?connection_option ] #
  29                 Connect over Unix-domain sockets
  30
  31         tcp:postgresql://host [ :port ] / [ database_name ] [
  32                 ?connection_option ] #
  33                 Connect over TCP/IP
  34
  35         SQL string constant #
  36                 containing a value in one of the above forms
  37
  38         host variable #
  39                 host variable of type char[] or VARCHAR[] containing a
  40                 value in one of the above forms
  41
  42    connection_name #
  43           An optional identifier for the connection, so that it can be
  44           referred to in other commands. This can be an SQL identifier or
  45           a host variable.
  46
  47    connection_user #
  48           The user name for the database connection.
  49
  50           This parameter can also specify user name and password, using
  51           one the forms user_name/password, user_name IDENTIFIED BY
  52           password, or user_name USING password.
  53
  54           User name and password can be SQL identifiers, string constants,
  55           or host variables.
  56
  57    DEFAULT #
  58           Use all default connection parameters, as defined by libpq.
  59
  60 Examples
  61
  62    Here a several variants for specifying connection parameters:
  63 EXEC SQL CONNECT TO "connectdb" AS main;
  64 EXEC SQL CONNECT TO "connectdb" AS second;
  65 EXEC SQL CONNECT TO "unix:postgresql://200.46.204.71/connectdb" AS main USER con
  66 nectuser;
  67 EXEC SQL CONNECT TO "unix:postgresql://localhost/connectdb" AS main USER connect
  68 user;
  69 EXEC SQL CONNECT TO 'connectdb' AS main;
  70 EXEC SQL CONNECT TO 'unix:postgresql://localhost/connectdb' AS main USER :user;
  71 EXEC SQL CONNECT TO :db AS :id;
  72 EXEC SQL CONNECT TO :db USER connectuser USING :pw;
  73 EXEC SQL CONNECT TO @localhost AS main USER connectdb;
  74 EXEC SQL CONNECT TO REGRESSDB1 as main;
  75 EXEC SQL CONNECT TO AS main USER connectdb;
  76 EXEC SQL CONNECT TO connectdb AS :id;
  77 EXEC SQL CONNECT TO connectdb AS main USER connectuser/connectdb;
  78 EXEC SQL CONNECT TO connectdb AS main;
  79 EXEC SQL CONNECT TO connectdb@localhost AS main;
  80 EXEC SQL CONNECT TO tcp:postgresql://localhost/ USER connectdb;
  81 EXEC SQL CONNECT TO tcp:postgresql://localhost/connectdb USER connectuser IDENTI
  82 FIED BY connectpw;
  83 EXEC SQL CONNECT TO tcp:postgresql://localhost:20/connectdb USER connectuser IDE
  84 NTIFIED BY connectpw;
  85 EXEC SQL CONNECT TO unix:postgresql://localhost/ AS main USER connectdb;
  86 EXEC SQL CONNECT TO unix:postgresql://localhost/connectdb AS main USER connectus
  87 er;
  88 EXEC SQL CONNECT TO unix:postgresql://localhost/connectdb USER connectuser IDENT
  89 IFIED BY "connectpw";
  90 EXEC SQL CONNECT TO unix:postgresql://localhost/connectdb USER connectuser USING
  91  "connectpw";
  92 EXEC SQL CONNECT TO unix:postgresql://localhost/connectdb?connect_timeout=14 USE
  93 R connectuser;
  94
  95    Here is an example program that illustrates the use of host variables
  96    to specify connection parameters:
  97 int
  98 main(void)
  99 {
 100 EXEC SQL BEGIN DECLARE SECTION;
 101     char *dbname     = "testdb";    /* database name */
 102     char *user       = "testuser";  /* connection user name */
 103     char *connection = "tcp:postgresql://localhost:5432/testdb";
 104                                     /* connection string */
 105     char ver[256];                  /* buffer to store the version string */
 106 EXEC SQL END DECLARE SECTION;
 107
 108     ECPGdebug(1, stderr);
 109
 110     EXEC SQL CONNECT TO :dbname USER :user;
 111     EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL CO
 112 MMIT;
 113     EXEC SQL SELECT version() INTO :ver;
 114     EXEC SQL DISCONNECT;
 115
 116     printf("version: %s\n", ver);
 117
 118     EXEC SQL CONNECT TO :connection USER :user;
 119     EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL CO
 120 MMIT;
 121     EXEC SQL SELECT version() INTO :ver;
 122     EXEC SQL DISCONNECT;
 123
 124     printf("version: %s\n", ver);
 125
 126     return 0;
 127 }
 128
 129 Compatibility
 130
 131    CONNECT is specified in the SQL standard, but the format of the
 132    connection parameters is implementation-specific.
 133
 134 See Also
 135
 136    DISCONNECT, SET CONNECTION