Permalink
Browse files

Documentation updates.

 * AUTHORS: Add Ronan Dunklau.
 * README:  Add features and requirements.
 * docs/index.rst: Add features and requirements and new issues page.
 * docs/issues.rst: New page to document known issues.
 * docs/overview.rst: Add Naming section.
  • Loading branch information...
1 parent a3d8d16 commit 0ad19d9a00cd402aea661e16f008da794abd71f7 @jmafc jmafc committed Dec 7, 2011
Showing with 116 additions and 32 deletions.
  1. +1 −0 AUTHORS
  2. +29 −8 README
  3. +26 −24 docs/index.rst
  4. +38 −0 docs/issues.rst
  5. +22 −0 docs/overview.rst
View
@@ -3,6 +3,7 @@ Pyrseas was started in 2010.
The PRIMARY AUTHORS are (and/or have been):
* Joe Abbate
+ * Ronan Dunklau
A big THANK YOU goes to:
View
37 README
@@ -3,13 +3,34 @@ Pyrseas
=======
Pyrseas provides a framework and utilities to upgrade and maintain a
-relational database. Its purpose is to enhance and follow through on
-the concepts of the `Andromeda Project
-<http://www.andromeda-project.org/>`_.
+PostgreSQL database.
-Pyrseas currently includes the dbtoyaml utility to create a `YAML
-<http://yaml.org/>`_ description of a PostgreSQL database's tables,
-and the yamltodb utility to generate SQL statements to modify a
-database to match an input YAML specification.
+Features
+--------
-Pyrseas is distributed under the BSD license.
+- Outputs a YAML/JSON description of a PostgreSQL database's tables
+ and other objects (metadata), suitable for storing in a version
+ control repository
+
+- Generates SQL statements to modify a database so that it will match
+ an input YAML/JSON specification
+
+- (planned) Generates a flexible web application to update PostgreSQL
+ tables
+
+Requirements
+------------
+
+- PostgreSQL 8.4 or higher
+
+- Python 2.6 or higher
+
+- (planned) Werkzeug
+
+- (planned) Jinja2
+
+License
+-------
+
+Pyrseas is free (libre) software and is distributed under the BSD
+license. Please see the LICENSE file for details.
View
@@ -2,27 +2,42 @@ Pyrseas
=======
Pyrseas provides a framework and utilities to upgrade and maintain a
-relational database. Its purpose is to enhance and follow through on
-the concepts of the `Andromeda Project
-<http://www.andromeda-project.org/>`_. The name comes from `Python
-<http://www.python.org/>`_, the programming language, and `Perseas
-<http://en.wikipedia.org/wiki/Perseus>`_ [#]_, the Greek mythological hero
-who rescued Andromeda from a sea monster [#]_.
+PostgreSQL database.
-Pyrseas currently includes the dbtoyaml utility to create a `YAML
-<http://yaml.org/>`_ description of a PostgreSQL database's tables,
-and the yamltodb utility to generate SQL statements to modify a
-database to match an input YAML specification.
+Features
+--------
+- Outputs a YAML/JSON description of a PostgreSQL database's tables
+ and other objects (metadata), suitable for storing in a version
+ control repository
-Contents:
+- Generates SQL statements to modify a database so that it willl match
+ an input YAML/JSON specification
+
+- (planned) Generates a flexible web application to update PostgreSQL
+ tables
+
+Requirements
+------------
+
+- `PostgreSQL <http://www.postgresql.org/>`_ 8.4 or higher
+
+- `Python <http://www.python.org/>`_ 2.6 or higher
+
+- (planned) Werkzeug
+
+- (planned) Jinja2
+
+Contents
+--------
.. toctree::
:maxdepth: 2
overview
install
testing
+ issues
.. toctree::
:maxdepth: 1
@@ -69,16 +84,3 @@ Indices and tables
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
-
-
-.. rubric:: Footnotes
-
-.. [#] The common English name for Perseas is Perseus and the Ancient
- Greek name is Perseos. However, in modern Greek Περσέας_ is the
- more common spelling for the mythical hero. The project would be
- Πυρσέας or ΠΥΡΣΕΑΣ in Greek.
-
-.. _Περσέας: http://en.wiktionary.org/wiki/%CE%A0%CE%B5%CF%81%CF%83%CE%AD%CE%B1%CF%82
-
-.. [#] He is better known for having killed Medusa.
-
View
@@ -0,0 +1,38 @@
+Known Issues
+============
+
+The following summarizes deficiencies in the current release of the
+Pyrseas utiltities. For further details please refer to the
+discussions in the pyrseas-general mailing list or the Pyrseas issue
+tracker. Suggestions or patches to deal with these issues are
+welcome.
+
+Memory utilization
+------------------
+
+The yamltodb utility compares the existing and input metadata by
+constructing parallel, in-memory representations of the database
+catalogs and the input YAML specification. If the database has a
+large number of objects, e.g., in the thousands of tables, the
+utility's memory usage may be noticeable.
+
+Object renaming
+---------------
+
+Pyrseas provides support for generating SQL statements to rename
+various database objects, e.g., ALTER TABLE t1 RENAME TO t2, using an
+'oldname' tag which can be added to objects that support SQL RENAME.
+The tag has to be added manually to a YAML specification for yamltodb
+to act on it and cannot be kept in the YAML file for subsequent runs.
+This is not entirely satisfactory for storing the YAML file in a
+version control system.
+
+Delimited identifiers
+---------------------
+
+PostgreSQL supports SQL delimited identifiers, i.e., object
+identifiers that include special characters (e.g., spaces, minus
+signs) or that are SQL reserved words. Pyrseas currently supports the
+first type of delimited identifiers, but not the use of reserved
+words, such as the tables named "order" or columns named "limit."
+Some work is in progress to address this issue.
View
@@ -75,3 +75,25 @@ the other hand, `Django's admin site application
more than one table on a web page, but it requires defining the
database "model" in Python and has limitations on how the database can
be structured.
+
+Naming
+------
+
+The project name comes from `Python <http://www.python.org/>`_, the
+programming language, and `Perseas
+<http://en.wikipedia.org/wiki/Perseus>`_ [#]_, the Greek mythological
+hero who rescued Andromeda from a sea monster [#]_. It is hoped that
+Pyrseas will rescue the Andromeda project <grin>. You can pronounce
+Pyrseas like the hero.
+
+
+.. rubric:: Footnotes
+
+.. [#] The common English name for Perseas is Perseus and the Ancient
+ Greek name is Perseos. However, in modern Greek Περσέας_ is the
+ more common spelling for the mythical hero. The project would be
+ Πυρσέας or ΠΥΡΣΕΑΣ in Greek.
+
+.. _Περσέας: http://en.wiktionary.org/wiki/%CE%A0%CE%B5%CF%81%CF%83%CE%AD%CE%B1%CF%82
+
+.. [#] He is better known for having killed Medusa.

0 comments on commit 0ad19d9

Please sign in to comment.