[mirrorbrain-commits] r7914 - in /trunk/docs: conf.py installation/source.rst mirrors.rst

From: <poeml_at_mirrorbrain.org>
Date: Sat, 05 Dec 2009 20:34:15 -0000
Author: poeml
Date: Sat Dec  5 21:34:13 2009
New Revision: 7914

URL: http://svn.mirrorbrain.org/viewvc/mirrorbrain?rev=7914&view=rev
Log:
docs:
- document the new "mb db" commands
- document the recommended cron job for database cleanups
- bump the version of the docs to 2.11.2

Modified:
    trunk/docs/conf.py
    trunk/docs/installation/source.rst
    trunk/docs/mirrors.rst

Modified: trunk/docs/conf.py
URL: http://svn.mirrorbrain.org/viewvc/mirrorbrain/trunk/docs/conf.py?rev=7914&r1=7913&r2=7914&view=diff
==============================================================================
--- trunk/docs/conf.py (original)
+++ trunk/docs/conf.py Sat Dec  5 21:34:13 2009
@@ -45,9 +45,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '2.11.1'
+version = '2.11.2'
 # The full version, including alpha/beta/rc tags.
-release = '2.11.1'
+release = '2.11.2'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

Modified: trunk/docs/installation/source.rst
URL: http://svn.mirrorbrain.org/viewvc/mirrorbrain/trunk/docs/installation/source.rst?rev=7914&r1=7913&r2=7914&view=diff
==============================================================================
--- trunk/docs/installation/source.rst (original)
+++ trunk/docs/installation/source.rst Sat Dec  5 21:34:13 2009
@@ -313,6 +313,12 @@
 
       44 0,4,8,12,16,20 * * *   mirrorbrain   mb scan -j 3 -a
 
+    another cron job can remove unreferenced files from the database::
+
+      # Monday: database clean-up day...
+      30 1 * * mon              mirrorbrain   mb db vacuum
+
+
 
 TODO: describe how to test that the install was successful
     (When testing, consider any excludes that you configured, and which may

Modified: trunk/docs/mirrors.rst
URL: http://svn.mirrorbrain.org/viewvc/mirrorbrain/trunk/docs/mirrors.rst?rev=7914&r1=7913&r2=7914&view=diff
==============================================================================
--- trunk/docs/mirrors.rst (original)
+++ trunk/docs/mirrors.rst Sat Dec  5 21:34:13 2009
@@ -62,6 +62,7 @@
     
     Commands:
         commentadd     add a comment about a mirror
+        db (vacuum)    perform database maintenance
         delete         delete a mirror from the database
         dirs           show directories that are in the database
         disable        disable a mirror
@@ -83,7 +84,7 @@
         show           show a mirror entry
         test           test if a mirror is working
         update         update mirrors network data in the database
-        vacuum         clean up unreferenced files from the mirror database
+
 
 
 By typing :program:`mb <command> -h` or :program:`mb help <command>`, help for
@@ -621,10 +622,97 @@
 Exporting in Django format
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-This is expiremental stuff — for hacking on the `Django`_ web framework. Data
-is exported in the form of Django ORM objects, and the export routine will very
-likely need modification for particular purposes. The existing code has been
-used to expirement with. Get in contact if you are interested in hacking on
-this!
+This is experimental stuff — intended for hacking on the `Django`_ web
+framework. Data is exported in the form of Django ORM objects, and the export
+routine will very likely need modification for particular purposes. The
+existing code has been used to experiment with. Get in contact if you are
+interested in hacking on this!
 
 .. _`Django`: http://www.djangoproject.com/
+
+
+Performing database maintenance
+-------------------------------
+
+The :program:`mb db` command offers some helpful functionality regarding
+database maintenance. It has several subcommands.
+
+
+Regular cleanups with :program:`mb db vacuum`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This command cleans up unreferenced files from the mirror database.
+
+This should be done once a week for a busy file tree.  Otherwise it should be
+rarely needed, but can possibly improve performance if it is able to shrink the
+database.
+
+When called with the ``-n`` option, only the number of files to be cleaned up
+is printed, so it's purely for information. No cleanup is performed.
+
+The recommended cron job looks like this::
+
+    # Monday: database clean-up day...
+    30 1 * * mon              mirrorbrain   mb db vacuum
+
+Note: This functionality is not to be confused with the PostgreSQL-internal
+vacuuming, which typically happens automatic these days (8.x), but was a manual
+process at some time in the past.
+
+
+Database shell with :program:`mb db shell`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+With this command, you can conveniently open a database shell::
+
+     % mb db shell
+    psql (8.4.1)
+    Type "help" for help.
+    
+    mb_opensuse=> 
+
+...ready to enter commands in psql, the `PostgreSQL interactive terminal`_.
+
+.. _`PostgreSQL interactive terminal`: http://www.postgresql.org/docs/8.4/static/app-psql.html
+
+
+Database size info with :program:`mb db size`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The command :program:`mb db size` prints the size of each database relation.
+(In PostgreSQL speak, a A *relation* is a table or an index.) This provides
+insight for appropriate database tuning and planning. Here's an example::
+
+     % mb db sizes       
+    Size(MB) Relation
+    464.5    filearr
+    532.9    filearr_path_key
+     74.3    filearr_pkey
+     23.8    pfx2asn
+     30.1    pfx2asn_pfx_key
+     19.9    pfx2asn_pkey
+      0.0    pg_foreign_server
+      0.0    pg_foreign_server_name_index
+      0.0    pg_foreign_server_oid_index
+      0.0    pg_user_mapping_user_server_index
+      0.2    server
+      0.0    server_enabled_status_baseurl_score_key
+      0.0    server_identifier_key
+      0.0    server_pkey
+      0.0    sql_sizing_profiles
+    Total: 1145.9
+
+That's a really large database, containing nearly 3 millions (!) of files. It
+uses a good gigabyte of disk space.
+
+``filearr`` contains the file names and associations to the mirrors.
+``filearr_path_key`` is the index on the file names. ``filearr_pkey`` is the
+primary key. These will be the largest things in a database filled with
+millions of files.
+
+The ``pfx*`` relations are only present when `mod_asn`_ is installed. The size
+they use is always the same.
+
+.. _`mod_asn`: http://mirrorbrain.org/mod_asn/
+
+




_______________________________________________
mirrorbrain-commits mailing list
Archive: http://mirrorbrain.org/archive/mirrorbrain-commits/

Note: To remove yourself from this list, send a mail with the content
 	unsubscribe
to the address mirrorbrain-commits-request_at_mirrorbrain.org
Received on Sat Dec 05 2009 - 20:34:18 GMT

This archive was generated by hypermail 2.2.0 : Sat Dec 05 2009 - 20:45:09 GMT