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         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.  Note the
 154                           troubleshooting section at the end of the cygrunsrv.README file.
 155
 156                 * Read the installation.html file
 157                   at /usr/doc/postgresql-x.x/html/installation.html
 158
 159                   In this file, you will run the following commands:
 160
 161                         * mkdir /usr/local/pgsql/data\r
 162                         * initdb -D /usr/local/pgsql/data\r
 163                         * postmaster -D /usr/local/pgsql/data >logfile 2>&1 &\r
 164                         * createdb test\r
 165                         * psql test
 166
 167                   When you need to connect to the database,
 168                   you will need ipc-daemon and postmaster running.  Start ipc-daemon
 169                   before any of the command above.
 170
 171                   psql is a command-line PostgreSQL client tool to
 172                   enter and run SQL commands and queries.
 173
 174                   If there is no database user named postgres, create a user named
 175                   postgres with the following SQL command in the client tool psql:
 176                         plsql test
 177                         create user postgres with password 'fun2db';
 178                   The only reason I say this is so you can easily use the System.Data tests
 179                   without having to change the database, userid, etc.
 180
 181         </ul>
 182
 183         In the path mcs/class/System.Data/Test
 184         there is a PostgreSQL test program named
 185         PostgreTest.cs.  Thanks goes to Gonzalo for creating the original
 186         PostgreSQL test.
 187         To use it to test System.Data, you
 188         modify the file to your PostgreSQL database
 189         connection requirements:
 190
 191         dbname is the database, ie, test
 192         host is the hostname of the PostgreSQL DBMS Server to connect to
 193         user is the username, ie, someuser
 194         password is the password, ie, mypass1234
 195
 196         The connection string is in OLE-DB connection string format.  Internally,
 197         SqlConnection converts this to the PostgreSQL connection string format.
 198
 199             OLE-DB: "host=localhost;dbname=test;user=joe;password=smoe"
 200         PostgreSQL: "host=localhost dbname=test user=joe password=smoe"
 201
 202         Note that OLE-DB includes the semicolons while PostgreSQL's connection
 203         string does not.
 204
 205     To compile the PostgresTest.cs program, do:
 206     mcs PostgresTest.cs -r System.Data
 207
 208     To run using mint, do:
 209     mint PostgresTest.exe
 210
 211     To run using mono, do:
 212     mono PostgresTest.exe
 213
 214     You should get something like:
 215
 216 Administrator@DANPC ~/mono/mcs/class/System.Data/Test\r
 217 $ mcs PostgresTest.cs -r System.Data\r
 218 \r
 219 Administrator@DANPC ~/mono/mcs/class/System.Data/Test\r
 220 $ mint PostgresTest.exe\r
 221         Postgres provider specific tests...\r
 222 \r
 223                 Drop table:\r
 224 Error (don't worry about this one)\r
 225                 Create table with all supported types:\r
 226 OK\r
 227                 Insert values for all known types:\r
 228 OK\r
 229                 Select values from the database:\r
 230                 Get Schema.\r
 231 dt.Columns.Count: 6\r
 232 * Column Name: int2_value\r
 233          MaxLength: 2\r
 234          Type: System.Int16\r
 235 * Column Name: int4_value\r
 236          MaxLength: 4\r
 237          Type: System.Int32\r
 238 * Column Name: bigint_value\r
 239          MaxLength: 8\r
 240          Type: System.Int64\r
 241 * Column Name: char_value\r
 242          MaxLength: -1\r
 243          Type: System.String\r
 244 * Column Name: varchar_value\r
 245          MaxLength: -1\r
 246          Type: System.String\r
 247 * Column Name: text_value\r
 248          MaxLength: -1\r
 249          Type: System.String\r
 250 Row 0:\r
 251     Col 0: int2_value - -22\r
 252     Col 1: int4_value - 1048000\r
 253     Col 2: bigint_value - 123456789012345\r
 254     Col 3: char_value - This is a char\r
 255     Col 4: varchar_value - This is a varchar\r
 256     Col 5: text_value - This is a text\r
 257 Rows: 1\r
 258 Clean up...\r
 259                 Drop table...\r
 260 OK\r
 261 \r