[Zope3-checkins] CVS: zopeproducts/psycopgda - README.txt:1.1

[Viktorija Zaksiene]

Update of /cvs-repository/zopeproducts/psycopgda
In directory cvs.zope.org:/tmp/cvs-serv7858

Added Files:
	README.txt 
Log Message:
Added documentation on using Zope3 with PostgreSQL via PsycopgDA.


=== Added File zopeproducts/psycopgda/README.txt ===
This file outlines the basics of using Zope3 with PostgreSQL via PsycopgDA.
In this document I'm assuming your Zope3 lives in ~/Zope3.


Installing PsycopgDA

  1. Check out the PsycopgDA product into ~/Zope3/src/zopeproducts

       cd ~/Zope3/src
       cvs -d :pserver:anonymous@cvs.zope.org:/cvs-repository login
       cvs -d :pserver:anonymous@cvs.zope.org:/cvs-repository checkout \
                                                zopeproducts/psycopgda

  2. Add the following line into ~/Zope3/products.zcml

       <include package='zopeproducts.psycopgda' />


Enabling SQL Connection Service

  3. Open a web browser on you Zope root folder (http://localhost:8080/ if
     you use the default settings in zserver.zcml).

  4. Click on the 'Manage Local Services' action on the right side of the
     screen.

  5. Go into the default package (click on 'Visit Default Package' in the
     actions box).

  6. Click on 'Add' in the actions box.

  7. Select 'SQL Connection Service'.
  
  8. You can enter the name for the service, but it is optional.  If you do
     not provide a name, your service will be called 'ConnectionService'.

  9. Click on the 'Add' button.

  10. You are again in the default package.  Click on an item called
      'configure'.

  11. Click on the 'Add' button.

  12. Select 'Service' and click on the 'Add' button.

  13. Select 'SQLDatabaseConnections' in the type drop-list.  Title and
      description are for informational purposes only.

  14. Click on the 'Next' button.

  15. Select the connection service component you added in step 8.

  16. Change the status to 'Active'.

  17. Click on the 'Finish' button.

  Whew!  You now have a functioning connection service.  That took some work.
  Let's hope the repetetive steps 10-17 will be eliminated in the future.


Creating Database Connections
  
  It is time to add some connections.

  18. Go back to the default package.

  19. Click on 'Add' in the actions box.

  20. Select 'Psycopg DA' and type in a name (the default is
      'zopeproducts.psycopgda', which is too cumbersome).

  21. Enter the database connection string.  It looks like this:

        dbi://username:password@host:port/databasename
  
  22. Click on the 'Add' button.
  
  23. You are again in the default package.  Click on the adapter you just
      added.

  24. Click on the 'Connect' button.  If you see an error message, go back
      and check the database connection string.

  25. If you want to, you can go to the Test page and execute arbitrary SQL
      queries to see whether the connection is working as expected.

  26. Go back to the default package.  Click on an item called 'configure'.

  27. Click on the 'Add' button.

  28. Select 'Connection' and click on the 'Add' button.

  29. Enter the connection name (it will be used later to identify
      connections used for SQLScripts).  I suggest using the same name as in
      step 20, to reduce confusion.

  30. Select the database adapter component you added in step 20.

  31. Select a permission that will be required to access the connection.
      (XXX: the input box or the drop-down?)

  32. Change the status to 'Active'.

  33. Click on the 'Submit Query' button.

  Repeat steps 18-33 for every connection you want to use.  Let's hope again
  that eventually there will be shortcuts for steps 23-24 and 26-30.


Using SQL Scripts
  
  You can create SQL Scripts in the content space.  For example:

  34. Go to Zope root.

  35. Add an SQL script (you can use the Common Tasks box on the left, or
      the Add action on the right).

  36. Click on the name of your new SQL script.

  37. Choose a connection name (the one you entered in step 29) from the
      drop-down.
  
  38. Enter your query and click on the 'Save Changes' button.

  39. You can test the script in the -- surprise! -- Test page.