[[Vorlage(Archiviert, "Das Python-Modul wird seit Frühjar 2018 nicht mehr weiter entwickelt.")]]

{{{#!vorlage Wissen
[:Pakete installieren: Installation von Programmen]
[:Terminal: Ein Terminal öffnen]
[:sudo:Root-Rechte]
}}}
[[Inhaltsverzeichnis()]]

[[Bild(couchdb-python.png, align=left)]]
[github:djc/couchdb-python:couchdb-python] ist ein Python-Modul, mit dessen Hilfe auf die dokumentenorientierte Datenbank [:CouchDB:] aus [:Python:] heraus zugegriffen werden kann. Weiterhin gibt es einen [http://packages.python.org/CouchDB/mapping.html Mapper] {en}, der die JSON-basierten Dokumente aus CouchDB auf Python-Objekt abbildet sowie ein [http://packages.python.org/CouchDB/views.html View Server] {en}, der es erlaubt, [:CouchDB#Views:CouchDB Views] für die Datenbank in Python zu schreiben.

Interessant ist couchdb-python aber auch für Nicht-Python-Programmierer, da zwei weitere Hilfsprogramme '''couchdb-dump''' und '''couchdb-load''' mit an Bord sind. Diese ermöglichen, eine Sicherung des Inhalts einer Datenbank lokal in eine Datei zu erstellen und diese dann auch wieder in eine Datenbank zurück zu spielen. Beides ist mit den Bordmittel von CouchDB so nicht möglich.

= Installation =
couchdb-python kann direkt aus den Quellen installiert werden[1], das zugehörige Paket heißt:

{{{#!vorlage Paketinstallation
python-couchdb
}}}

== Manuell ==
Die Version aus den Quellen ist nicht unbedingt die aktuellste Version. Wer diese benötigt, der kann das neuste Modul z.B. auch über [:pip:] installieren. Der entsprechende Befehl lautet[2]:

{{{#!vorlage Befehl
pip couchdb #für Python 2
pip3 couchdb #für Python 3
}}}

Bei systemweiter Installation muss der Befehl mit Root-Rechten[3] ausgeführt werden.

= Benutzung =
== Python-Modul ==
Wer das Modul für eigene Projekte nutzen möchte, der sollte sich mit den beiden Hauptklassen `couchdb.client` und `couchdb.schema` beschäftigen. Erstere enthält alle benötigten Klassen und Methoden zum Abfragen der Datenbank sowie zum Anlegen von Datenbanken und Dokumenten, letztere stellt den eingangs erwähnten Mapper bereit.

Eine ausführliche Beschreibung mit vielen Beispielen ist in der [http://packages.python.org/CouchDB/ offiziellen Dokumentation] {en} zu finden.

== Hilfsprogramme ==
Wie in der Einleitung bereits erwähnt, bringt couchdb-python zwei Hilfsprogramme mit, mit deren Hilfe sich eine Datenbank komplett, also sowohl Dokumente als auch Views, lokal in eine einzige Datei sichern und auch aus dieser Datei wieder zurück spielen lassen. Dies ist z.B. dann nützlich, wenn man eine Datenbank zwischen zwei CouchDB Servern transferieren will, welche nicht im selben Netzwerk sind, so dass keine Replikation möglich ist.

Technisch gesehen wird beim Dump die Datenbank einfach in eine einzige große Textdatei geschrieben, wobei der Inhalt im Format [wikipedia:JSON:] abgelegt wird. Dabei wird immer nur die aktuellste Revision gesichert wird.

Der Befehl zum Sichern einer Datenbank (hier: `MEINE_DB`) in eine Datei (hier: '''mein.dump''') lautet[2]:

{{{#!vorlage Befehl
couchdb-dump http://localhost:5984/MEINE_DB > mein.dump
}}}

Der Befehl zum Zurückspielen in die Datenbank `MEINE_NEUE_DB` lautet:

{{{#!vorlage Befehl
couchdb-load http://localhost:5984/MEINE_NEUE_DB < mein.dump
}}}

Da für die Zieldatenbank alle Dokumente neu sind, beginnt hier die Revisionszählung wieder bei eins - unabhängig davon, welche Revisionsnummern die Dokumente in der Ausgangsdatenbank hatten. Wenn die Revisionsnummern also beim Transfer der Dokumente erhalten bleiben soll, ist der Weg via `couchdb-dump` und `couchdb-load` also nicht der geeignete.

= Problembehebung =
== couchdb-dump bricht mit einen UnicodeEncodeError ab ==
couchdb-dump (aus der Version 0.8 des Pakets '''python-couchdb''') bricht den Dump mit einem "UnicodeEncodeError" ab, wenn die ID eines Dokuments Nicht-ASCII-Zeichen (wie z.B. `äöüß`) enthält. Details inkl. Patches siehe auch [googlecode:couchdb-python/issues/detail?id=179: Ticket 179] {en}

Ab [:Xenial:Ubuntu 16.04] ist der Fehler behoben.

= Links =
 * [github:djc/couchdb-python:Projektseite] {en}
 * [github:benoitc/couchdbkit:Couchdbkit] {en} - alternatives Python-Modul für CouchDB
 * [:CouchDB:]

#tag: Programmierung, Datensicherung, Python