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