doc/ado-net

   1 * ADO.NET
   2
   3         The coordinator for the ADO.NET implementation is <a
   4         href="mailto:rodrigo@ximian.com">Rodrigo Moya</a>, with
   5         the collaboration of <a href="mailto:danmorg@sc.rr.com">Daniel
   6         Morgan</a>.
   7
   8 * Action plan
   9
  10         The current plan to implement ADO.NET is as follows:
  11
  12         <b>Step 1:</b> SqlClient:
  13
  14         <ul>
  15                 * Implementation of System.Data.SqlClient based on
  16                   the PostgreSQL C API.
  17
  18                 * Once the System.Data.SqlClient code is functional and
  19                   is usable by other people, we willl move it to
  20                   System.Data.PostgreSQL, and will convert the existing
  21                   System.Data.SqlClient to be just a wrapper around
  22                   System.Data.PostgreSQL.
  23
  24         </ul>
  25
  26         <b>Step 2:</b> OleDB:
  27         <ul>
  28                 * On Unix systems: System.Data.OleDb will use LibGDA as its
  29                   engine.
  30
  31                   LibGDA is the data access engine that is used by
  32                   Gnome-Db (only libgda, not libgnomedb at all).
  33
  34                 * On Windows systems: System.Data.OleDb will use OLE-DB as
  35                   its engine.  It may have the option of using libgda too.
  36         </ul>
  37
  38         <b>Step 3:</b> System.Data.SqlClient Provider:
  39
  40         <ul>
  41                 * System.Data.SqlClient will then become a managed
  42                   provider for MS SQL Server, both on Windows and
  43                   Linux, to be compatible with applications written
  44                   for MS .NET.
  45         </ul>
  46
  47         <b>Step 4:</b> Other System.Data providers:
  48
  49         <ul>
  50                 * The idea in MS .NET System.Data seems to be to have
  51                   a managed provider for each supported DBMS. So, apart
  52                   from System.Data.OleDb (generic) and System.Data.SqlClient,
  53                   we'll need to have System.Data.ODBC, System.Data.MySQL,
  54                   System.Data.Oracle, System.Data.PostgreSQL, etc. Others,
  55                   of course, are welcomed.
  56         </ul>
  57
  58 * Current Status
  59         >
  60         <p>We are able to do simple CREATE TABLE, DROP TABLE, INSERT, and
  61         DELETE SQL commands using the ExecuteNonQuery method in SqlCommand.
  62
  63         <p>We are also able to do simple aggregate functions,
  64         ie, count(), sum(), avg(), min(), and
  65         max() in a simple SELECT SQL query using ExecuteSecalar() now.
  66
  67         <p>We are also able to retrieve data with a simple SELECT SQL query
  68         using ExecuteReader() which returns a SqlDataReader.  We are able to
  69         use GetSchemaTable() to get the meta data about the table columns.
  70         We are able     to Read() to get each row from the result set.  We are able to get
  71         String data (char, bpchar (character), text, varchar), Int16 (int2 or smallint),
  72         and Int32 (int4 or integer), and Int64 (int8 or bigint).  More data types will
  73         follow later on.
  74
  75         <p>Parameters are not working nor has stored procedures
  76         been tested - but they will be.
  77
  78         <p>A lot of functionality in System.Data is missing, but the
  79         infrastructure is starting to come together.
  80
  81         <p>To compile that test program, you need:
  82
  83         <b>On Linux</b>
  84
  85         <ul>
  86                 * update your mono sources.
  87
  88                 * get the files from mcs/class/lib/*.dll and mcs/mcs/mcs*
  89                   built on windows, and put them on your
  90                   linux machine.
  91
  92                 * compile the test program along with the System.Data,
  93                   System.Data.Common, System.Data.SqlClient, and
  94                   System.Data.SqlTypes.
  95         </ul>
  96
  97 * Testing
  98
  99         <p>In order to test System.Data.SqlClient, you will need to have
 100         access to a remote PostgreSQL DBMS, or you will have to install
 101         one locally.  PostgreSQL is the DBMS used for the initial
 102         implementation of System.Data.SqlClient.
 103
 104         <p>Why?  Because it is open source, has a client
 105         library that is easy to use, PostgreSQL is easy to install
 106         using the Cygwin install program, not difficult to setup after
 107         installation, and it runs under: Linux,
 108         Windows (via cygwin and ipc-daemon), Unix, and
 109         others.  This allowed us to create the
 110         System.Data functionality in Mono much quicker.
 111
 112         <p>If you plan on using a remote PostgreSQL DBMS Server,
 113         than you will need to have the PostgreSQL client software on your
 114         local computer that includes libpq.so (pq.dll on Windows).
 115
 116         <p>Installation instructions for PostgreSQL DBMS:
 117
 118         <b>On Linux</b>
 119
 120         <ul>
 121                 * TODO
 122
 123                 * It easier to install PostgreSQL on Linux than Windows.
 124         </ul>
 125
 126         <b>On Windows</b>
 127
 128         <ul>
 129                 * Use the cygwin installer to install the PostgreSQL DBMS.  It is
 130                   found in the database category.
 131
 132                 * <p>Read the file postgres-x.x.README at /usr/doc/Cygwin and read
 133                   the requirements to install PostgreSQL.  Those requirements
 134                   are included with cygwin except cygipc.  A default installtion
 135                   of cygwin does not install everything you will need, so on the
 136                   safe side, just include everything when installing cygwin.
 137
 138                   <p>The -x.x in postgres-x.x is the version of your PostgreSQL DBMS.
 139
 140                 * <p>Once cygwin has installed PostgreSQL on your computer,
 141                   read the file FAQ_MSWIN which is available
 142                   in /usr/doc/postgres-x.x\FAQ_MSWIN
 143
 144                   <p>The -x.x in postgres-x.x is the version of your PostgreSQL DBMS.
 145
 146                   <p>Important notes from this file are:
 147
 148                   <ul>
 149                         * <p>Point 2. - Install the latest cygipc package,
 150                           available at
 151                           http://www.neuro.gatech.edu/users/cwilson/cygutils/V1.1/cygipc/
 152
 153                           <p>The cygipc package contains the ipc-daemon you will need
 154                           to run before you can
 155                           run the PostgreSQL DBMS Server daemon (postmaster) or run
 156                           initdb which initializes the PostgreSQL database.
 157
 158                         * <p>Point 3.  The Cygwin bin directory has to be placed in
 159                           the path before the Windows program directories,
 160                           for example, C:\cygwin\bin
 161
 162                           My own note, in the Windows control panel, I set
 163                           the environment variables PATH to my cygwin /usr/local/bin,
 164                           /usr/bin, and /bin.  I also set my LD_LIBRARY_PATH to
 165                           /usr/local/lib and /usr/lib.  For example:
 166
 167                         * <p>
 168 <pre>
 169 PATH=c:\cygwin\usr\local\bin;c:\cygwin\usr\bin;c:\cygwin\bin;
 170 LD_LIBRARY_PATH=c:\cygwin\usr\local\lib;c:\cygwin\usr\lib;
 171 </pre>
 172
 173                           </p>
 174                         * <p>Point 4. Start the ipc-daemon that came with the cygipc package.  There
 175                           are two ways to do this: run it from the command line as:
 176
 177                           <p>
 178 <pre>
 179 ipc-daemon &
 180 </pre>
 181
 182                           <p>or you can set it up as a Windows service.  See the
 183                           file cygrunsrv.README at /usr/doc/Cygwin on how to do this
 184                           for ipc-daemon and postmaster.  Note the
 185                           troubleshooting section at the end of
 186                           the cygrunsrv.README file.
 187
 188                           <p>To install ipc-daemon as a service,
 189                           you just have to run
 190
 191                           <p>
 192 <pre>
 193 ipc-daemon --install-as-service' (--remove-as-service)
 194 </pre>
 195
 196                           <p>
 197                           and then run
 198
 199 <pre>
 200 net start ipc-daemon
 201 </pre>
 202                           </ul>
 203
 204                 * <p>Read the installation.html file
 205                   at /usr/doc/postgresql-x.x/html/installation.html
 206
 207                   <p>You will see in this file that you will need to
 208                   run the following commands:
 209
 210 <pre>
 211 mkdir /usr/local/pgsql/data\r
 212 initdb -D /usr/local/pgsql/data\r
 213 postmaster -D /usr/local/pgsql/data >logfile 2>&1 &\r
 214 createdb test\r
 215 psql test
 216 </pre>
 217
 218                 * <p>When you need to connect to the database,
 219                   you will need ipc-daemon and postmaster running.  Start ipc-daemon
 220                   before any of the command above.
 221
 222                 * <p>psql is a command-line PostgreSQL client tool to
 223                   enter and run SQL commands and queries.
 224
 225                 * <p>If there is no database user named postgres, create a user named
 226                   postgres with the following SQL command in the client tool psql:
 227
 228                   <p>
 229 <pre>
 230 plsql test
 231 create user postgres with password 'fun2db';
 232 </pre>
 233
 234                   <p>The only reason I say this is so you can easily use the System.Data tests
 235                   without having to change the database, userid, etc.
 236         </ul>
 237
 238         <p>In the path mcs/class/System.Data/Test
 239         there is a PostgreSQL test program named
 240         PostgreTest.cs.  Thanks goes to Gonzalo for creating the original
 241         PostgreSQL test.
 242
 243         <p>To use it to test System.Data, you
 244         modify the file to your PostgreSQL database
 245         connection requirements:
 246
 247         <p>
 248 <pre>
 249 dbname is the database, ie, test
 250 host is the hostname of the PostgreSQL DBMS Server to connect to
 251 user is the username, ie, someuser
 252 password is the password, ie, mypass1234
 253 </pre>
 254
 255         <p>The connection string is in OLE-DB connection string format.  Internally,
 256         SqlConnection converts this to the PostgreSQL connection string format.
 257
 258         <p>
 259 <pre>
 260 OLE-DB: "host=localhost;dbname=test;user=joe;password=smoe"
 261 PostgreSQL: "host=localhost dbname=test user=joe password=smoe"
 262 </pre>
 263
 264         <p>
 265         Note that OLE-DB includes the semicolons while PostgreSQL's connection
 266         string does not.
 267
 268         <p>
 269     To compile the PostgresTest.cs program, do:
 270
 271     <p>
 272 <pre>
 273 mcs PostgresTest.cs -r System.Data
 274 </pre>
 275
 276     <p>
 277     To run using mint, do:
 278
 279     <p>
 280 <pre>
 281 mint PostgresTest.exe
 282 </pre>
 283
 284     <p>
 285     To run using mono, do:
 286 <pre>
 287 mono PostgresTest.exe
 288 </pre>
 289
 290     <p>You should get something like:
 291
 292 <p>
 293 <pre>
 294  Administrator@DANPC ~/mono/mcs/class/System.Data/Test\r
 295  $ mcs PostgresTest.cs -r System.Data\r
 296 \r
 297  Administrator@DANPC ~/mono/mcs/class/System.Data/Test\r
 298  $ mint PostgresTest.exe\r
 299          Postgres provider specific tests...\r
 300 \r
 301                  Drop table:\r
 302  Error (don't worry about this one)\r
 303                  Create table with all supported types:\r
 304  OK\r
 305                  Insert values for all known types:\r
 306  OK\r
 307                  Select values from the database:\r
 308                  Get Schema.\r
 309  dt.Columns.Count: 6\r
 310  * Column Name: int2_value\r
 311           MaxLength: 2\r
 312           Type: System.Int16\r
 313  * Column Name: int4_value\r
 314           MaxLength: 4\r
 315           Type: System.Int32\r
 316  * Column Name: bigint_value\r
 317           MaxLength: 8\r
 318           Type: System.Int64\r
 319  * Column Name: char_value\r
 320           MaxLength: -1\r
 321           Type: System.String\r
 322  * Column Name: varchar_value\r
 323           MaxLength: -1\r
 324           Type: System.String\r
 325  * Column Name: text_value\r
 326           MaxLength: -1\r
 327           Type: System.String\r
 328  Row 0:\r
 329      Col 0: int2_value - -22\r
 330      Col 1: int4_value - 1048000\r
 331      Col 2: bigint_value - 123456789012345\r
 332      Col 3: char_value - This is a char\r
 333      Col 4: varchar_value - This is a varchar\r
 334      Col 5: text_value - This is a text\r
 335  Rows: 1\r
 336  Clean up...\r
 337                  Drop table...\r
 338  OK\r
 339 </pre>\r
 340 \r