**** Merged from MCS ****

[mono-project.git] / mcs / class / ByteFX.Data / mysqlclient / docs / MySqlConnection.xml

<MyDocs>\r
<MyMembers name="Class">\r
<remarks>\r
        <para>\r
                A <b>MySqlConnection</b> object represents a session to a MySQL Server \r
                data source.  When you create an instance of <B>MySqlConnection</B>, all \r
                properties are set to their initial values. For a list of these values, see the \r
                <B>MySqlConnection</B> constructor.\r
        </para>\r
\r
        <para>\r
                If the <B>MySqlConnection</B> goes out of scope, it is not closed. Therefore, \r
                you must explicitly close the connection by calling <see cref="MySqlConnection.Close"/> \r
                or <see cref="MySqlConnection.Dispose"/>.\r
        </para>\r
\r
</remarks>\r
\r
<example>\r
        The following example creates a <see cref="MySqlCommand"/> and \r
        a <B>MySqlConnection</B>. The <B>MySqlConnection</B> is opened and set as the  \r
        <see cref="MySqlCommand.Connection"/> for the <B>MySqlCommand</B>. The example then calls  \r
        <see cref="MySqlCommand.ExecuteNonQuery"/>, and closes the connection. To accomplish this, the <B>ExecuteNonQuery</B> is \r
        passed a connection string and a query string that is a SQL INSERT \r
        statement.\r
        <code lang="Visual Basic">\r
        <c>\r
Public Sub InsertRow(myConnectionString As String)\r
        ' If the connection string is null, use a default.\r
        If myConnectionString = "" Then\r
                myConnectionString = "Database=Test;Data Source=localhost;User Id=username;Password=pass"\r
        End If\r
        Dim myConnection As New MySqlConnection(myConnectionString)\r
        Dim myInsertQuery As String = "INSERT INTO Orders (id, customerId, amount) Values(1001, 23, 30.66)"\r
        Dim myCommand As New MySqlCommand(myInsertQuery)\r
        myCommand.Connection = myConnection\r
        myConnection.Open()\r
        myCommand.ExecuteNonQuery()\r
        myCommand.Connection.Close()\r
End Sub\r
</c> \r
        </code>\r
        <code lang="C#">\r
<c>\r
public void InsertRow(string myConnectionString) \r
{\r
        // If the connection string is null, use a default.\r
        if(myConnectionString == "") \r
        {\r
                myConnectionString = "Database=Test;Data Source=localhost;User Id=username;Password=pass";\r
        }\r
        MySqlConnection myConnection = new MySqlConnection(myConnectionString);\r
        string myInsertQuery = "INSERT INTO Orders (id, customerId, amount) Values(1001, 23, 30.66)";\r
        MySqlCommand myCommand = new MySqlCommand(myInsertQuery);\r
        myCommand.Connection = myConnection;\r
        myConnection.Open();\r
        myCommand.ExecuteNonQuery();\r
        myCommand.Connection.Close();\r
}\r
</c>\r
        </code>\r
</example>\r
\r
\r
</MyMembers>\r
\r
<MyMembers name="ConnectionTimeout">\r
        <exception cref="System.ArgumentException">The value set is less than 0.</exception>\r
        <remarks>\r
                A value of 0 indicates no limit, and should be avoided in a \r
                <see cref="MySqlConnection.ConnectionString"/> because an attempt to connect \r
                will wait indefinitely.\r
        </remarks>\r
        <example>\r
                The following example creates a MySqlConnection\r
                and sets some of its properties in the connection string.\r
                <code lang="Visual Basic">\r
Public Sub CreateSqlConnection()\r
        Dim myConnection As New MySqlConnection()\r
        myConnection.ConnectionString = "Persist Security Info=False;Username=user;Password=pass;database=test1;server=localhost;Connect Timeout=30"\r
        myConnection.Open()\r
End Sub\r
</code>\r
<code lang="C#">\r
public void CreateSqlConnection() \r
{\r
        MySqlConnection myConnection = new MySqlConnection();\r
        myConnection.ConnectionString = "Persist Security Info=False;Username=user;Password=pass;database=test1;server=localhost;Connect Timeout=30";\r
        myConnection.Open();\r
}\r
</code>                         \r
        </example>\r
</MyMembers>\r
\r
\r
<MyMembers name="ConnectionString">\r
        <remarks>\r
        <para>The <B>ConnectionString</B> returned may not be exactly like what was originally\r
        set but will be indentical in terms of keyword/value pairs.  Security information\r
        will not be included unless the Persist Security Info value is set to true. \r
        </para>\r
        <para>You can use the <B>ConnectionString</B> property to connect to a database. \r
        The following example illustrates a typical connection string.</para>\r
        <c>"Persist Security Info=False;database=MyDB;server=MySqlServer;user id=myUser;Password=myPass"</c>\r
        <para>The <B>ConnectionString</B> property can be set only when the connection is \r
        closed. Many of the connection string values have corresponding read-only \r
        properties. When the connection string is set, all of these properties are \r
        updated, except when an error is detected. In this case, none of the properties \r
        are updated. <see cref="MySqlConnection"/> properties return only those settings contained in the \r
        <B>ConnectionString</B>.</para>\r
        <para>To connect to a local machine, specify "localhost" for the server. If you do not \r
        specify a server, localhost is assumed.</para>\r
        <para>Resetting the <B>ConnectionString</B> on a closed connection resets all \r
        connection string values (and related properties) including the password. For \r
        example, if you set a connection string that includes "Database= MyDb", and \r
        then reset the connection string to "Data Source=myserver;User Id=myUser;Password=myPass", \r
        the <see cref="MySqlConnection.Database"/> property is no longer set to MyDb.</para>\r
        <para>The connection string is parsed immediately after being set. If errors in \r
        syntax are found when parsing, a runtime exception, such as <see cref="ArgumentException"/>, \r
        is generated. Other errors can be found only when an attempt is made to open the \r
        connection.</para>\r
        <para>The basic format of a connection string consists of a series of keyword/value \r
        pairs separated by semicolons. The equal sign (=) connects each keyword and its \r
        value. To include values that contain a semicolon, single-quote character, or \r
        double-quote character, the value must be enclosed in double quotes. If the \r
        value contains both a semicolon and a double-quote character, the value can be \r
        enclosed in single quotes. The single quote is also useful if the value begins \r
        with a double-quote character. Conversely, the double quote can be used if the \r
        value begins with a single quote. If the value contains both single-quote and \r
        double-quote characters, the quote character used to enclose the value must be \r
        doubled each time it occurs within the value.</para>\r
        <para>To include preceding or trailing spaces in the string value, the value must \r
        be enclosed in either single quotes or double quotes. Any leading or trailing \r
        spaces around integer, Boolean, or enumerated values are ignored, even if \r
        enclosed in quotes. However, spaces within a string literal keyword or value are \r
        preserved. Using .NET Framework version 1.1, single or double quotes may be used \r
        within a connection string without using delimiters (for example, Data Source= \r
        my'Server or Data Source= my"Server), unless a quote character is the first or \r
        last character in the value.</para>\r
        <para>To include an equal sign (=) in a keyword or value, it must be preceded by \r
        another equal sign. For example, in the hypothetical connection string</para>\r
        <c>"key==word=value"</c>\r
        <para></para>\r
        <para>the keyword is "key=word" and the value is "value".</para>\r
        <para>If a specific keyword in a keyword= value pair occurs multiple times in a \r
        connection string, the last occurrence listed is used in the value set.</para>\r
        <para>Keywords are not case sensitive.</para>\r
        <para>The following table lists the valid names for keyword values within the \r
        <B>ConnectionString</B>.</para>\r
        <div class="tablediv"><table class="dtTABLE" cellspacing="0"><tr valign="top">\r
                <th width="33%">Name</th>\r
                <th width="33%">Default</th>\r
                <th width="33%">Description</th>\r
                </tr>\r
                <tr>\r
                        <td>Connect Timeout<para>  -or-  </para>Connection Timeout</td>\r
                        <td>15</td>\r
                        <td>The length of time (in seconds) to wait for a connection to the server before \r
terminating the attempt and generating an error.</td>\r
                </tr>\r
                <tr>\r
                        <td>\r
                                Host<para>  -or-  </para>Server<para>  -or-  </para>Data Source<para>  -or-  </para>\r
                                DataSource<para>  -or-  </para>Address<para>  -or-  </para>Addr<para>  -or-  </para>\r
                                Network Address\r
                        </td>\r
                        <td>localhost</td>\r
                        <td><para>The name or network address of the instance of MySQL to which to connect.  Multiple hosts can be\r
                        specified separated by &amp;.  This can be useful where multiple MySQL servers are configured for replication\r
                        and you are not concerned about the precise server you are connecting to.  No attempt is made by the provider to\r
                        synchronize writes to the database so care should be taken when using this option.\r
                        </para>\r
                        <para>\r
                                In Unix environment with Mono, this can be a fully qualified path to MySQL socket filename. With this configuration, the Unix socket will be used instead of TCP/IP socket.\r
                                Currently only a single socket name can be given so accessing MySQL in a replicated environment using Unix sockets is not currently supported.\r
                        </para>\r
                        </td>\r
                </tr>\r
                <tr>\r
                        <td>Port</td>\r
                        <td>3306</td>\r
                        <td>The port MySQL is using to listen for connections.  Specify -1 for this value to use a \r
                                named pipe connection (Windows only). This value is ignored if Unix socket is used.</td>\r
                </tr>\r
                <tr>\r
                        <td>Encrypt</td>\r
                        <td>false</td>\r
                        <td>When <B>true</B>, SSL encryption is used for all data sent between the \r
client and server if the server has a certificate installed. Recognized values \r
are <B>true</B>, <B>false</B>, <B>yes</B>, and <B>no</B>.<para><b>Note</b>  This parameter currently has no\r
effect.</para></td>\r
                </tr>\r
                <tr>\r
                        <td>Initial Catalog<para>  -or-  </para>Database</td>\r
                        <td></td>\r
                        <td>The name of the database to use intially</td>\r
                </tr>\r
                <tr>\r
                        <td>Password<para>  -or-  </para>pwd</td>\r
                        <td></td>\r
                        <td>The password for the MySQL account being used.</td>\r
                </tr>\r
                <tr>\r
                        <td>Persist Security Info</td>\r
                        <td>false</td>\r
                        <td>When set to <B>false</B> or <B>no</B> (strongly recommended), security-sensitive \r
information, such as the password, is not returned as part of the connection if \r
the connection is open or has ever been in an open state. Resetting the \r
connection string resets all connection string values including the password. \r
Recognized values are <B>true</B>, <B>false</B>, <B>yes</B>, and <B>no</B>.</td>\r
                </tr>\r
                <tr>\r
                        <td>User Id<para>  -or-  </para>Username<para>  -or-  </para>Uid<para>  -or-  </para>User name</td>\r
                        <td></td>\r
                        <td>The MySQL login account being used.</td>\r
                </tr>\r
                </table>\r
                </div>\r
        <para>\r
        The following table lists the valid names for connection pooling values within \r
the <B>ConnectionString</B>. For more information about connection pooling, see \r
Connection Pooling for the ByteFX Data Provider for MySQL.</para>\r
        <div class="tablediv"><table class="dtTABLE" cellspacing="0"><tr valign="top">\r
                <th width="33%">Name</th>\r
                <th width="33%">Default</th>\r
                <th width="33%">Description</th>\r
                </tr>\r
                <tr>\r
                        <td>Connection Lifetime</td>\r
                        <td>0</td>\r
                        <td>When a connection is returned to the pool, its creation time is compared with \r
the current time, and the connection is destroyed if that time span (in seconds) \r
exceeds the value specified by <B>Connection Lifetime</B>. This is useful in \r
clustered configurations to force load balancing between a running server and a \r
server just brought online. \r
<para>A value of zero (0) causes pooled connections to have the maximum connection \r
timeout.</para></td>\r
                </tr>\r
                <tr>\r
                        <td>Max Pool Size</td>\r
                        <td>100</td>\r
                        <td>The maximum number of connections allowed in the pool.</td>\r
                </tr>\r
                <tr>\r
                        <td>Min Pool Size</td>\r
                        <td>0</td>\r
                        <td>The minimum number of connections allowed in the pool.</td>\r
                </tr>\r
                <tr>\r
                        <td>Pooling</td>\r
                        <td>true</td>\r
                        <td>When <B>true</B>, the <B>MySqlConnection</B> object is drawn from the appropriate \r
pool, or if necessary, is created and added to the appropriate pool. Recognized \r
values are <B>true</B>, <B>false</B>, <B>yes</B>, and <B>no</B>.</td>\r
                </tr>\r
                <tr>\r
                        <td>Use Pipe<para>  -or-  </para>Pipe</td>\r
                        <td></td>\r
                        <td>When set to the name of a named pipe, the <B>MySqlConnection</B> will attempt to connect to MySQL\r
                        on that named pipe.<br/><br/>This settings only applies to the Windows platform.</td>\r
                </tr>\r
        </table></div>\r
<para>When setting keyword or connection pooling values that require a Boolean \r
value, you can use 'yes' instead of 'true', and 'no' instead of 'false'.</para>\r
<para><B>Note</B>  The ByteFX Data Provider for MySQL uses the native socket protocol to \r
communicate with MySQL.  Therefore, it does not support the use of an ODBC data source name (DSN) when \r
connecting to MySQL because it does not add an ODBC layer.</para>\r
<para><B>CAUTION</B>  In this release, the application should use caution when constructing a \r
connection string based on user input (for example when retrieving user ID and password information from a \r
dialog box, and appending it to the connection string). The application should \r
ensure that a user cannot embed extra connection string parameters in these \r
values (for example, entering a password as "validpassword;database=somedb" in \r
an attempt to attach to a different database).</para>\r
        </remarks>\r
        <example>\r
        The following example creates a <see cref="MySqlConnection"/> and sets some of its properties\r
        <code lang="Visual Basic">\r
        Public Sub CreateConnection()\r
                Dim myConnection As New MySqlConnection()\r
                myConnection.ConnectionString = "Persist Security Info=False;database=myDB;server=myHost;Connect Timeout=30;user id=myUser; pwd=myPass"\r
                myConnection.Open()\r
        End Sub 'CreateConnection\r
        </code>\r
        <code lang="C#">\r
        public void CreateConnection() \r
        {\r
                MySqlConnection myConnection = new MySqlConnection();\r
                myConnection.ConnectionString = "Persist Security Info=False;database=myDB;server=myHost;Connect Timeout=30;user id=myUser; pwd=myPass";\r
                myConnection.Open();\r
        }\r
        </code>\r
</example>\r
        <example>\r
                The following example creates a <see cref="MySqlConnection"/> in Unix environment with Mono installed. MySQL socket filename used in this example is "/var/lib/mysql/mysql.sock". The actual filename depends on your MySQL configuration.\r
        <code lang="Visual Basic">\r
        Public Sub CreateConnection()\r
                Dim myConnection As New MySqlConnection()\r
                myConnection.ConnectionString = "database=myDB;server=/var/lib/mysql/mysql.sock;user id=myUser; pwd=myPass"\r
                myConnection.Open()\r
        End Sub 'CreateConnection\r
        </code>\r
        <code lang="C#">\r
        public void CreateConnection() \r
        {\r
                MySqlConnection myConnection = new MySqlConnection();\r
                myConnection.ConnectionString = "database=myDB;server=/var/lib/mysql/mysql.sock;user id=myUser; pwd=myPass";\r
                myConnection.Open();\r
        }\r
        </code>\r
        </example>\r
</MyMembers>\r
</MyDocs>\r