web/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.
  36         </ul>
  37
  38         <b>Step 3:</b> System.Data.SqlClient Providers:
  39
  40         <ul>
  41                 * System.Data.SqlClient will then become a generic
  42                   proxy for binding to other SQL implementations other
  43                   than PostgreSQL (MySQL on Unix/Windows; MS SQL on
  44                   Window; Interbase on Unix/Windows). Others are welcomed.
  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         GetSchemaTable() get the meta data about the table columns.  We are able
  70         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), Int64 (int8 or bigint).  More data types will
  73         follow later on.
  74
  75         <p>Parameters are not working nor has stored procedures been tested - but they will be.
  76
  77         <p>A lot of functionality in System.Data is missing, but the infrastructure is
  78         starting to come together.
  79
  80         <p>To compile that test program, you need:
  81
  82         <b>On Linux</b>
  83
  84         <ul>
  85                 * update your mono sources.
  86
  87                 * get the .dll's and mcs.exe built on windows, and put them on your
  88                   linux machine.
  89
  90                 * compile the test program along with the System.Data.Common and
  91                   System.Data.SqlClient files.
  92         </ul>
  93
  94 * Testing
  95
  96         <p>In order to test System.Data.SqlClient, you will need to have
  97         access to a remote PostgreSQL DBMS, or you will have to install
  98         one locally.  PostgreSQL is the DBMS used for the initial
  99         implementation of System.Data.SqlClient.
 100
 101         <p>Why?  Because it is open source, has a client
 102         library that is easy to use, PostgreSQL is easy to install
 103         using the Cygwin install program, not difficult to setup after
 104         installation, and it runs under: Linux,
 105         Windows (via cygwin and ipc-daemon), Unix, and
 106         others.  This allowed us to create the
 107         System.Data functionality in Mono much quicker.
 108
 109         <p>If you plan on using a remote PostgreSQL DBMS Server,
 110         than you will need to have the PostgreSQL client software on your
 111         local computer that includes libpq.so (pq.dll on Windows).
 112
 113         <p>Installation instructions for PostgreSQL DBMS:
 114
 115         <b>On Linux</b>
 116
 117         <ul>
 118                 * TODO
 119
 120                 * It easier to install PostgreSQL on Linux than Windows.
 121         </ul>
 122
 123         <b>On Windows</b>
 124
 125         <ul>
 126                 * Use the cygwin installer to install the PostgreSQL DBMS.  It is
 127                   found in the database category.
 128
 129                 * <p>Read the file postgres-x.x.README at /usr/doc/Cygwin and read
 130                   the requirements to install PostgreSQL.  Those requirements
 131                   are included with cygwin except cygipc.  A default installtion
 132                   of cygwin does not install everything you will need, so on the
 133                   safe side, just include everything when installing cygwin.
 134
 135                   <p>The -x.x in postgres-x.x is the version of your PostgreSQL DBMS.
 136
 137                 * <p>Once cygwin has installed PostgreSQL on your computer,
 138                   read the file FAQ_MSWIN which is available
 139                   in /usr/doc/postgres-x.x\FAQ_MSWIN
 140
 141                   <p>The -x.x in postgres-x.x is the version of your PostgreSQL DBMS.
 142
 143                   <p>Important notes from this file are:
 144
 145                   <ul>
 146                         * <p>Point 2. - Install the latest cygipc package,
 147                           available at
 148                           http://www.neuro.gatech.edu/users/cwilson/cygutils/V1.1/cygipc/
 149
 150                           The cygipc package contains the ipc-daemon you will need
 151                           to run before you can
 152                           run the PostgreSQL DBMS Server daemon (postmaster) or run
 153                           initdb which initializes the PostgreSQL database.
 154
 155                         * <p>Point 3.  The Cygwin bin directory has to be placed in
 156                           the path before the Windows program directories,
 157                           for example, C:\cygwin\bin
 158
 159                           My own note, in the Windows control panel, I set
 160                           the environment variables PATH to my cygwin /usr/local/bin,
 161                           /usr/bin, and /bin.  I also set my LD_LIBRARY_PATH to
 162                           /usr/local/lib and /usr/lib.  For example:
 163
 164                           <p><pre>
 165                           PATH=c:\cygwin\usr\local\bin;c:\cygwin\usr\bin;c:\cygwin\bin;
 166                           LD_LIBRARY_PATH=c:\cygwin\usr\local\lib;c:\cygwin\usr\lib;
 167                           </pre>
 168
 169                           </p>
 170                         * <p>Point 4. Start the ipc-daemon that came with the cygipc package.  There
 171                           are two ways to do this: run it from the command line as:
 172
 173                           <p>
 174                           <pre>
 175                                 ipc-daemon &
 176                           </pre>
 177
 178                           <p>or you can set it up as a Windows service.  See the
 179                           file cygrunsrv.README at /usr/doc/Cygwin on how to do this
 180                           for ipc-daemon and postmaster.  Note the
 181                           troubleshooting section at the end of
 182                           the cygrunsrv.README file.
 183
 184                           <p>To install ipc-daemon as a service,
 185                           you just have to run
 186
 187                           <p>
 188                           <pre>
 189                           ipc-daemon --install-as-service' (--remove-as-service)
 190                           </pre>
 191
 192                           <p>
 193                           and then run
 194
 195                           <pre>
 196                           net start ipc-daemon
 197                           </pre>
 198                           </ul>
 199
 200                 * <p>Read the installation.html file
 201                   at /usr/doc/postgresql-x.x/html/installation.html
 202
 203                   <p>In this file, you will run the following commands:
 204
 205                   <pre>
 206                         mkdir /usr/local/pgsql/data\r
 207                         initdb -D /usr/local/pgsql/data\r
 208                         postmaster -D /usr/local/pgsql/data >logfile 2>&1 &\r
 209                         createdb test\r
 210                         psql test
 211                   </pre>
 212
 213                   <p>When you need to connect to the database,
 214                   you will need ipc-daemon and postmaster running.  Start ipc-daemon
 215                   before any of the command above.
 216
 217                   <p>psql is a command-line PostgreSQL client tool to
 218                   enter and run SQL commands and queries.
 219
 220                   <p>If there is no database user named postgres, create a user named
 221                   postgres with the following SQL command in the client tool psql:
 222
 223                   <p>
 224                   <pre>
 225                         plsql test
 226                         create user postgres with password 'fun2db';
 227                   </pre>
 228
 229                   <p>The only reason I say this is so you can easily use the System.Data tests
 230                   without having to change the database, userid, etc.
 231         </ul>
 232
 233         <p>In the path mcs/class/System.Data/Test
 234         there is a PostgreSQL test program named
 235         PostgreTest.cs.  Thanks goes to Gonzalo for creating the original
 236         PostgreSQL test.
 237
 238         <p>To use it to test System.Data, you
 239         modify the file to your PostgreSQL database
 240         connection requirements:
 241
 242         <p>
 243         <pre>
 244         dbname is the database, ie, test
 245         host is the hostname of the PostgreSQL DBMS Server to connect to
 246         user is the username, ie, someuser
 247         password is the password, ie, mypass1234
 248         </pre>
 249
 250         <p>The connection string is in OLE-DB connection string format.  Internally,
 251         SqlConnection converts this to the PostgreSQL connection string format.
 252
 253         <p>
 254         <pre>
 255             OLE-DB: "host=localhost;dbname=test;user=joe;password=smoe"
 256         PostgreSQL: "host=localhost dbname=test user=joe password=smoe"
 257         </pre>
 258
 259         <p>
 260         Note that OLE-DB includes the semicolons while PostgreSQL's connection
 261         string does not.
 262
 263         <p>
 264     To compile the PostgresTest.cs program, do:
 265
 266     <p>
 267     <pre>
 268     mcs PostgresTest.cs -r System.Data
 269     </pre>
 270
 271     <p>
 272     To run using mint, do:
 273
 274     <p>
 275     <pre>
 276     mint PostgresTest.exe
 277     </pre>
 278
 279     <p>
 280     To run using mono, do:
 281     <pre>
 282     mono PostgresTest.exe
 283     </pre>
 284
 285     <p>You should get something like:
 286
 287 <p>
 288 <pre>
 289 Administrator@DANPC ~/mono/mcs/class/System.Data/Test\r
 290 $ mcs PostgresTest.cs -r System.Data\r
 291 \r
 292 Administrator@DANPC ~/mono/mcs/class/System.Data/Test\r
 293 $ mint PostgresTest.exe\r
 294         Postgres provider specific tests...\r
 295 \r
 296                 Drop table:\r
 297 Error (don't worry about this one)\r
 298                 Create table with all supported types:\r
 299 OK\r
 300                 Insert values for all known types:\r
 301 OK\r
 302                 Select values from the database:\r
 303                 Get Schema.\r
 304 dt.Columns.Count: 6\r
 305 * Column Name: int2_value\r
 306          MaxLength: 2\r
 307          Type: System.Int16\r
 308 * Column Name: int4_value\r
 309          MaxLength: 4\r
 310          Type: System.Int32\r
 311 * Column Name: bigint_value\r
 312          MaxLength: 8\r
 313          Type: System.Int64\r
 314 * Column Name: char_value\r
 315          MaxLength: -1\r
 316          Type: System.String\r
 317 * Column Name: varchar_value\r
 318          MaxLength: -1\r
 319          Type: System.String\r
 320 * Column Name: text_value\r
 321          MaxLength: -1\r
 322          Type: System.String\r
 323 Row 0:\r
 324     Col 0: int2_value - -22\r
 325     Col 1: int4_value - 1048000\r
 326     Col 2: bigint_value - 123456789012345\r
 327     Col 3: char_value - This is a char\r
 328     Col 4: varchar_value - This is a varchar\r
 329     Col 5: text_value - This is a text\r
 330 Rows: 1\r
 331 Clean up...\r
 332                 Drop table...\r
 333 OK\r
 334 </pre>\r