[office/kmymoney/Handbook-5.2] /: finish database chapter
Jack Ostroff
null at kde.org
Tue Nov 28 19:18:42 GMT 2023
Git commit a8f0189c0ae0c42976e62b3d9808c5f90b946fee by Jack Ostroff.
Committed on 28/11/2023 at 20:18.
Pushed by ostroffjh into branch 'Handbook-5.2'.
finish database chapter
M +10 -1 README-CONTRIBUTORS
M +245 -207 doc/details-database.docbook
M +247 -115 doc/details-formats.docbook
M +4 -4 doc/details-settings.docbook
A +- -- doc/file-backup.png
https://invent.kde.org/office/kmymoney/-/commit/a8f0189c0ae0c42976e62b3d9808c5f90b946fee
diff --git a/README-CONTRIBUTORS b/README-CONTRIBUTORS
index 424cae9db..44a186719 100644
--- a/README-CONTRIBUTORS
+++ b/README-CONTRIBUTORS
@@ -91,11 +91,14 @@ This is in the order pulled in from index.docbook, with brief note on state of u
prelim update complete
<!ENTITY details-formats SYSTEM "details-formats.docbook">
+ prelim update complete
<!ENTITY details-database SYSTEM "details-database.docbook">
+ prelim update complete
<!ENTITY details-settings SYSTEM "details-settings.docbook">
-
+ prelim update begun
+
<!ENTITY faq SYSTEM "faq.docbook">
<!ENTITY reference SYSTEM "reference.docbook">
@@ -352,3 +355,9 @@ elsewhere.
- Cant search results be sorted any more? (Could they ever?)
+- Need to mention in file formats chapter that all data files can be stored locally
+ or on a network share. Also mention mounting the share is often an issue on Windows.
+
+- what does File/Backup do if SQL is the current file type?
+
+-
\ No newline at end of file
diff --git a/doc/details-database.docbook b/doc/details-database.docbook
index eb2ea8f09..cef1b46c1 100644
--- a/doc/details-database.docbook
+++ b/doc/details-database.docbook
@@ -3,253 +3,281 @@
<chapterinfo>
<authorgroup>
<author>&Tony.Bloomfield; &Tony.Bloomfield.mail;</author>
+ <author> &Jack.H.Ostroff; &Jack.H.Ostroff.mail; </author>
</authorgroup>
- <date>2011-07-21</date>
- <releaseinfo>4.6</releaseinfo>
+ <date>2023-11-25</date>
+ <releaseinfo>5.2</releaseinfo>
</chapterinfo>
<title>Database</title>
-<sect1 id="details.database.usage">
-<title>Using relational databases</title>
+<sect1 id="details.database.usage"><title>Using relational databases</title>
+
+<sect2><title>Introduction</title>
-<sect2>
-<title>Introduction</title>
<para>
- As of release 1.0, &kmymoney; allows you to hold your data in a relational
- database. One of the advantages of using this industry-standard format is that
- it may allow you to view your data using one of the graphic front ends such as
- <trademark>OpenOffice.org</trademark> or <trademark>LibreOffice</trademark>,
- perhaps in some format that &kmymoney; currently doesn't
- provide. Also, a little knowledge of SQL (Structured Query Language, the
- language used world-wide to access relational databases) should enable you
- more easily to export data to an external program, for example, a budgeting
- application.
+ Since release 1.0, &kmymoney; allows you to hold your data in a relational
+ database. One of the advantages of using this industry-standard format is that it
+ may allow you to view your data using one of the graphic front ends such as
+ <trademark>OpenOffice.org</trademark> or <trademark>LibreOffice</trademark>, or
+ perhaps in some format that &kmymoney; currently doesn't provide. Also, a little
+ knowledge of <acronym><ulink url="https://en.wikipedia.org/wiki/SQL">SQL</ulink>
+ </acronym> (<quote>Structured Query Language</quote>, the language used world-wide
+ to access relational databases) should enable you more easily to export data to an
+ external program, for example, a budgeting application.
</para>
-<para/>
+
+<note>
+ <para>
+ Although most relational database systems allow concurrent access to a database
+ by more than one user, this is not possible with &kmymoney;. Even though
+ &kmymoney; can store its data in a relational database, it actually behaves as if
+ the database is just a different type of file storage. When you open your file,
+ the program reads all of the data from the database. As you work with your data,
+ the changes are made only to the internal storage; they are not immediately
+ written back to the database. Only when you save your data does &kmymoney; write
+ the entire file back to the database.
+ </para>
+
+ <para>
+ There have been requests for &kmymoney; to update the database for each data
+ change, but this would require a significant change to the entire way the program
+ manages its internal data structures, so this is extremely unlikely to happen in
+ the foreseeable future.
+ </para>
+</note>
</sect2>
<sect2><title>Preparation</title>
<para>
- To access the database, &kmymoney; uses the SQL module supplied by &Qt;
- Software as part of their &Qt; programming system. This module supports a
- number of different database systems through a collection of drivers. Among
- the more popular open-source systems for which drivers are available are
- <trademark>MySQL</trademark>, SQLite (version 3 and upwards only), and PostgreSQL.
- The module also supports the 'heavier', more industrial, systems such as <trademark
- class="registered">Oracle</trademark> and IBM <trademark class="registered">DB2</trademark>.
+ To access the database, &kmymoney; uses the SQL module supplied by &Qt; Software as
+ part of their &Qt; programming system. This module supports many database systems
+ through a collection of drivers. &Qt; has drivers for a large numeber of open
+ source and proprietary relational database systems, including
+ <trademark>MySQL</trademark>, PostgreSQL, and Sqlcipher. The module also supports
+ some 'heavier', more industrial, systems such as <trademark
+ class="registered">Oracle</trademark> and IBM <trademark
+ class="registered">DB2</trademark>.
</para>
<para>
- With the exception of SQLite, these systems use a client/server model, where
- the 'client' software sits on 'your' machine, while the server lives on the
- same machine as the database itself, which may be elsewhere on a network. Of
- course, in the normal scenario for a personal finance application such as
- &kmymoney;, 'your' machine acts as both client and server. Your first task
- therefore, having decided which database system you wish to use, is to install
- the client, and most probably server, software.
+ Previous versions of &kmymoney; supported <ulink
+ url="https://www.sqlite.org">SQLite</ulink>. This has been replaced with support
+ for <ulink url="https://www.zetetic.net/sqlcipher">SQLCipher</ulink>, which is a
+ standalone fork of the SQLite database library that adds 256 bit AES encryption and
+ other security features. The SQLCipher driver will read existing SQLite files.
+</para>
+
+<para>
+ With the exception of SQLCipher, these systems use a client/server model, where the
+ 'client' software sits on 'your' machine, while the server lives on the same
+ machine as the database itself, which may be elsewhere on a network. Of course, in
+ the normal scenario for a personal finance application such as &kmymoney;, 'your'
+ machine can act as both client and server. Your first task therefore, having
+ decided which database system you wish to use, is to install the client, and most
+ probably server, software.
</para>
<para>
In addition to the database software itself, you must also install the
- corresponding &Qt; driver module. Most distributions will include driver
- modules for the more popular databases. Otherwise, check with the <ulink
- url="https://www.qt.io/">&Qt; software web site</ulink> and search for
- 'SQL drivers'.
+ corresponding &Qt; driver module. Most &Linux; distributions will include driver
+ modules for the more popular databases. Otherwise, check with the <ulink
+ url="https://www.qt.io/">&Qt; software web site</ulink> and search for <quote>SQL
+ drivers</quote>.
+ <!-- FIXME: what about Windows and macOS? -->
</para>
<note>
<para>
- SQLite does not operate on a client/server model; each database is held in a
- regular file, local or remote, accessed using the normal methods supplied by
- the underlying operating system. In this case, therefore, there is only one
- software package and the driver to install. Also, some of the following information,
- particularly that related to administration, may not apply to SQLite.
+ SQLCipher and SQLite do not operate on a client/server model; each database is
+ held in a regular file, local or remote, accessed using the normal methods
+ supplied by the underlying operating system. In this case, therefore, there is
+ only one software package and the driver to install. Also, some of the following
+ information, particularly that related to administration, may not apply.
</para>
</note>
</sect2>
-<sect2>
-<title>Administration</title>
+<sect2><title>Administration</title>
<para>
- Looking after databases is a little more complex than dealing with regular
- files. Each system has different methods for performing those necessary
- administrative tasks such as creating databases, assigning permissions to
- various users, producing backups, &etc; Describing these tasks is outside the
- scope of this manual, but all of the supported products provide comprehensive
- reference documentation, and a quick search of the web will point you at many
- tutorials on the subject.
+ Looking after databases is a little more complex than dealing with regular files.
+ Each system has different methods for performing those necessary administrative
+ tasks such as creating databases, assigning permissions to various users, or
+ producing backups. Describing these tasks is outside the scope of this manual, but
+ all of the supported products provide comprehensive reference documentation, and a
+ quick search of the web will point you at many tutorials on the subject.
</para>
-<sect3>
-<title>Creating the database</title>
+<sect3><title>Creating the database</title>
<para>
- Code has been included to create an initial database to hold your data if one
- doesn't exist. However, it is strongly recommended that you pre-create a
- database, because most of the products provide a number of options which may
- be relevant. One that may be of particular importance to some would be the
- designation of the character set (⪚, UTF-8) to be used for text
- fields.
+ &kmymoney; includes SQL code to create an initial database to hold your data if one
+ doesn't exist. However, it is strongly recommended that you pre-create a database,
+ because most of the products provide a number of options which may be relevant.
+ One that may be of particular importance to some would be the designation of the
+ character set (⪚, UTF-8) to be used for text fields.
</para>
<para>
At this time, you will also need to specify permissions for various users to
- perform different operations on the database. In most systems, the user who
- creates the database will be automatically assigned all permissions, but this
- is an area in which the documentation should be consulted.
+ perform different operations on the database. In most systems, the user who
+ creates the database will be automatically assigned all permissions, but this is an
+ area in which the documentation should be consulted.
</para>
<para>
For your first use of the database, and occasionally at other times when the
database layout changes, you will need permission (also called privileges) to
- create and alter tables and views (see next paragraph). There may be different
+ create and alter tables and views (see next paragraph.) There may be different
names for the permission/privilege in different systems, but something like
- <literal>CREATE</literal> and <literal>ALTER</literal> should be commonplace.
- For normal running, you will need to be able to read and write records; these
- are normally defined in SQL as <literal>SELECT</literal>, <literal>INSERT</literal>,
+ <literal>CREATE</literal> and <literal>ALTER</literal> should be commonplace. For
+ normal running, you will need to be able to read and write records; these are
+ normally defined in SQL as <literal>SELECT</literal>, <literal>INSERT</literal>,
<literal>UPDATE</literal>, and <literal>DELETE</literal> permissions.
</para>
</sect3>
-<sect3>
-<title>Creating Tables</title>
+<sect3><title>Creating Tables</title>
<para>
On your first use, &kmymoney; will attempt to create the necessary table
- structures. In order to achieve the maximum compatibility between various
- database types, only a subset of common data types are used. There may
- nevertheless be situations where a particular type is not supported, and in
- this case, provision has been made to generate the SQL code necessary to
- create tables. This code can then be modified as required and used to create
- the tables outside of &kmymoney;. Should you find yourself in this situation,
- help can usually be obtained from &devlist;. See <link
- linkend="details.database.generatesql">Manual Database Creation</link> for more information.
+ structures. In order to achieve the maximum compatibility between various database
+ types, only a subset of common data types are used. There may nevertheless be
+ situations where a particular type is not supported, and in this case, provision
+ has been made to generate the SQL code necessary to create the tables. This code
+ can then be modified as required and used to create the tables outside of
+ &kmymoney;. Should you find yourself in this situation, help can usually be
+ obtained from one of the channels listed in the section on <link
+ linkend="firsttime.contact">Getting Help</link>. See <link
+ linkend="details.database.generatesql">Manual Database Creation</link> for more
+ information.
</para>
</sect3>
</sect2>
-<sect2 id="details.database.selectdatabase">
-<title>Creating a Database</title>
+<sect2 id="details.database.selectdatabase"><title>Creating a Database</title>
<para>
- Using &kmymoney;, open or import an existing data file, or create a new
- one. Then select <menuchoice><guimenu>File</guimenu><guimenuitem>Save as Database</guimenuitem></menuchoice>
- menu item. This will present the following dialog:
+ Using &kmymoney;, open or import an existing data file, or create a new one. Then
+ select <menuchoice><guimenu>File</guimenu><guimenuitem>Save as
+ Database</guimenuitem></menuchoice> menu item. Select <guilabel>SQL</guilabel>
+ from the <guilabel>Storage type to use for your data</guilabel> dropdown, and click
+ <guibutton>OK</guibutton>.
+ You will then see the following dialog:
</para>
<screenshot>
<mediaobject>
- <imageobject>
- <imagedata fileref="select_database.png" format="PNG" />
- </imageobject>
+ <imageobject>
+ <imagedata fileref="select_database.png" format="PNG" />
+ </imageobject>
</mediaobject>
</screenshot>
<para>
- Complete the fields appropriate to the database type you have selected
- (as usual, mandatory fields will be highlighted)
- and click <guibutton>OK</guibutton> to create the database.
+ Complete the fields appropriate to the database type you have selected (as usual,
+ mandatory fields will be highlighted) and click <guibutton>OK</guibutton> to create
+ the database.
</para>
-<sect3>
-<title>Database Type</title>
+<sect3><title>Database Type</title>
<para>
- This box lists all &Qt; SQL drivers installed on your system. Select the
- driver for your database type. If the one you want is not in the list, you
- need to install the appropriate driver. See your distribution documentation,
- or visit the <ulink url="https://www.qt.io/">&Qt; software web site</ulink>
- and search for 'SQL drivers'.
+ This box lists all the &Qt; SQL drivers installed on your system. Select the
+ driver for your database type. If the one you want is not in the list, you need to
+ install the appropriate driver. See your distribution documentation, or visit the
+ <ulink url="https://www.qt.io/">&Qt; software web site</ulink> and search for 'SQL
+ drivers'.
</para>
</sect3>
-<sect3>
-<title>File (SQLite only)</title>
+<sect3><title>File (SQLite only)</title>
+
<para>
- SQLite has one database per file so enter the filename in which you wish to
- create the database. To browse the file system, click the icon to the right
- of the filename. For SQLite databases, the <guilabel>Host name</guilabel>,
- <guilabel>Username</guilabel>, and <guilabel>Password</guilabel> fields are
- not relevant. The SQLite file must have the appropriate read/write permissions
- set by the underlying file system to enable the appropriate access for the
- currently logged-in user.
+ SQLCipher has one database per file so enter the filename in which you wish to
+ create the database. To browse the file system, click the icon to the right of the
+ filename. For SQLCipher databases, the <guilabel>Database Name</guilabel>,
+ <guilabel>Host name</guilabel>, <guilabel>Username</guilabel> fields are not
+ relevant. The SQLCipher file must have the appropriate read/write permissions set
+ by the underlying file system to enable the appropriate access for the currently
+ logged-in user.
</para>
</sect3>
<sect3>
<title>Database name (others)</title>
<para>
- The default database name is <literal>KMyMoney</literal>, but you may choose some other
- name if you like. For some database types, &kmymoney; may not be able to create the
- database, so it must be pre-created using the appropriate administrative procedure.
- However, &kmymoney; will usually be able to create all table structures where necessary.
- If not, you can create them yourself. See <link linkend="details.database.generatesql">Manual
- Database Creation</link> for more information.
+ The default database name is <literal>KMyMoney</literal>, but you may choose some
+ other name if you like. For some database types, &kmymoney; may not be able to
+ create the database, so it must be pre-created using the appropriate administrative
+ procedure. However, &kmymoney; will usually be able to create all table structures
+ where necessary. If not, you can create them yourself. See <link
+ linkend="details.database.generatesql">Manual Database Creation</link> for more
+ information.
</para>
</sect3>
<sect3><title>Host name</title>
+
<para>
For the average user, the default name of <quote>localhost</quote>, being the
- machine you are currently using, is correct. For networked databases, enter
- the connected host name.
+ machine you are currently using, is correct. For networked databases, enter the
+ connected host name of the database server.
</para>
-
</sect3>
-<sect3>
-<title>User name and password</title>
+<sect3><title>User name and password</title>
+
<para>
Check the permissions set up on your database, or contact the database
- administrator, for the correct values to use here. The user name must be
- capable of selecting, inserting, updating, and deleting records. If the user
- name is the same as your login name, a password is not normally required.
+ administrator, for the correct values to use here. The user name must be capable
+ of selecting, inserting, updating, and deleting records. If the user name is the
+ same as your login name, a password is not normally required.
</para>
</sect3>
</sect2>
-<sect2>
-<title>Accessing your data</title>
+<sect2><title>Accessing your data</title>
-<sect3>
-<title>Table design</title>
+<sect3><title>Table design</title>
<para>
- To access your data in &kmymoney;, use the <menuchoice><guimenu>File</guimenu><guimenuitem>Open
- Database</guimenuitem></menuchoice> menu item. This will
- open a dialog similar to the above.
+ To access your data in &kmymoney;, use the <menuchoice> <guimenu>File</guimenu>
+ <guimenuitem>Open Database</guimenuitem> </menuchoice> menu item. This will open a
+ dialog similar to the above.
</para>
<note>
-<para>
- If you created your database by first opening a file, and then doing
- <guimenuitem>Save as Database</guimenuitem>, as described above, then any
- subsequent changes to your data are saved only in the database, not in the
- file. This means that you can use the file as a backup or snapshot of your
- data at a particular time. To make a new backup like this, open your
- database, choose the <menuchoice><guimenu>File</guimenu><guimenuitem>Save
- As...</guimenuitem></menuchoice> menu item, giving an appropriate file name. Remember
- to re-open your database, so &kmymoney; does not continue to use the file.
-</para>
+ <para>
+ If you created your database by first opening a file, and then doing <guimenu>File</guimenu>
+ <guimenuitem>Save</guimenuitem> and choosing
+ <guilabel>SQL</guilabel> as described above, then any subsequent changes to your
+ data are saved only in the database, not in the file. This means that you can use
+ the file as a backup or snapshot of your data at a particular time. To make a new
+ backup like this, open your database, choose the <menuchoice>
+ <guimenu>File</guimenu> <guimenuitem>Save As...</guimenuitem></menuchoice> menu
+ item, chose <guilabel>XML</guilabel> as the storage type, and giving an
+ appropriate file name. Remember to re-open your database, so &kmymoney; does not
+ continue to use the file.
+ </para>
</note>
<para>
- To access your data in other formats, you will need to know a little about how
- it is held in relational databases. By far the easiest way to get a feel for
- this is to open the database in a front-end such as <trademark>OpenOffice.org</trademark>.
- This provides a list of the various tables which make up the database, and
- enables you to see the layout of each of them.
+ To access your data in other formats, you will need to know a little about how it
+ is held in relational databases. By far the easiest way to get a feel for this is
+ to open the database in a front-end such as <trademark>OpenOffice.org</trademark>.
+ This provides a list of the various tables which make up the database, and enables
+ you to see the layout of each of them.
</para>
<para>
- To extract data, ⪚, into a spreadsheet or external file, it is almost
- invariably necessary to select linked data from more than one table. This is
- done by 'joining' the tables, using a field which is common to each. You can
+ To extract data, ⪚, into a spreadsheet or external file, it is almost invariably
+ necessary to select linked data from more than one table. This is done by
+ <quote>joining</quote> the tables, using a field which is common to them. You can
find a lot more information about how this is done from the online database
- tutorials mentioned above. The following table lists the fields used to define
+ tutorials mentioned above. The following table lists the fields used to define
these inter-table relationships.
</para>
@@ -387,6 +415,11 @@
Notes:
</para>
+<!-- FIXME: can anyone explain why we should use these character codes?
+ – en dash
+ “ left double quote
+ ” right double quote
+-->
<para>
1 – txType = “N” for normal transactions,
“S” for scheduled transactions
@@ -397,128 +430,133 @@
</para>
</sect3>
-<sect3>
-<title>Field formats</title>
+<sect3><title>Field formats</title>
<para>
Several of the data fields are held in an internal format which may not be
- immediately useful to external programs. In these cases, the information has
- been duplicated in both internal and external formats.
+ immediately useful to external programs. In these cases, the information has been
+ duplicated in both internal and external formats.
</para>
<para>
- Monetary amounts and share values are shown both in numerator/denominator
- format, and, with a field name suffixed with '<literal>Formatted</literal>',
- in the form as shown on your screens.
+ Monetary amounts and share values are shown both in numerator/denominator format,
+ and, with a field name suffixed with <quote> <literal>Formatted</literal> </quote>,
+ in the form as typically displayed.
</para>
<para>
- Similarly, some fields, such as account type appear both as a numeric code,
- and in a field suffixed '<literal>String</literal>' in the form and language
- of the application.
+ Similarly, some fields, such as account type appear both as a numeric code, and in
+ a field suffixed '<literal>String</literal>' in the form and language of the
+ application.
</para>
</sect3>
-<sect3>
-<title>Updating your data</title>
+<sect3><title>Updating your data</title>
<para>
- Having data in an industry standard format does give you the ability to modify
- it outside the &kmymoney; application. DO NOT DO IT unless you really know
- what you are doing, and always be certain to make a backup copy of your data
- first. If you get it wrong, &kmymoney; may not be able to access your data,
- and you could even end up losing it altogether. You have been warned!
+ Having data in an industry standard format does give you the ability to modify it
+ outside the &kmymoney; application. DO NOT DO IT unless you really know what you
+ are doing, and always be certain to make a backup copy of your data first. If you
+ get it wrong, &kmymoney; may not be able to access your data, and you could even
+ end up losing it altogether. You have been warned!
</para>
</sect3>
-<sect3>
-<title>Stored queries</title>
+<sect3><title>Stored queries</title>
<para>
- Most database systems allow you to store commonly used queries and procedures,
- and in some cases, these may be held as tables or other objects within your
- database itself. As you will have guessed from the above, all the tables used
- by &kmymoney; begin with the lowercase letters '<literal>kmm</literal>'. This
- standard will be maintained, and only tables beginning with these letters will
- be updated. Thus, provided you avoid these in the naming of your queries &etc;,
- you should not experience any problems.
+ Most database systems allow you to store commonly used queries and procedures, and
+ in some cases, these may be held as tables or other objects within your database
+ itself. As you will have guessed from the above, all the tables used by &kmymoney;
+ begin with the lowercase letters '<literal>kmm</literal>'. This standard will be
+ maintained, and only tables beginning with these letters will be updated. Thus,
+ provided you avoid these in the naming of your queries &etc;, you should not
+ experience any problems.
</para>
</sect3>
</sect2>
-<sect2 id="details.database.generatesql">
-<title>Manual database creation</title>
+<sect2 id="details.database.generatesql"><title>Manual database creation</title>
+
<note>
<para>
This section covers more advanced database usage and may be skipped by the general user.
</para>
</note>
-<sect3>
-<title>When to use</title>
+<sect3><title>When to use</title>
+
<para>
- There may be occasions when &kmymoney; is unable to create the database automatically, or creates it without some
- options required by the user. For example, the database system used may not completely conform
- to standard SQL usage, or support may be introduced for new systems which have not been fully tested in &kmymoney;.
+ There may be occasions when &kmymoney; is unable to create the database
+ automatically, or creates it without some options required by the user. For
+ example, the database system used may not completely conform to standard SQL usage,
+ or support may be introduced for new systems which have not been fully tested in
+ &kmymoney;.
</para>
+
<para>
- Prior to using this facility, you should try just creating the database
- entry itself (&ie; with the <literal>CREATE DATABASE</literal> statement).
- Provided the database exists, &kmymoney; may well be able to create the
- tables, &etc; in the normal database save procedure described above.
+ Prior to using this facility, you should try just creating the database entry
+ itself (&ie; with the <literal>CREATE DATABASE</literal> statement). Provided the
+ database exists, &kmymoney; may well be able to create the tables, &etc; in the
+ normal database save procedure described above.
</para>
</sect3>
-<sect3>
-<title>Generating the SQL</title>
+<sect3><title>Generating the SQL</title>
+
<para>
- If this fails, it is possible to generate the basic SQL commands needed to
- create the various tables, views and indexes required by the application.
- Select the <menuchoice><guimenu>Tools</guimenu><guimenuitem>Generate Database
- SQL</guimenuitem></menuchoice> menu item. This will present the following dialog:
+ If this fails, it is possible to generate the basic SQL commands needed to create
+ the various tables, views, and indexes required by the application. Select the
+ <menuchoice> <guimenu>Tools</guimenu> <guimenuitem>Generate Database
+ SQL</guimenuitem> </menuchoice> menu item. This will present the following dialog:
</para>
+
<screenshot>
<mediaobject>
- <imageobject>
- <imagedata fileref="generate_sql.png" format="PNG" />
- </imageobject>
+ <imageobject>
+ <imagedata fileref="generate_sql.png" format="PNG" />
+ </imageobject>
</mediaobject>
</screenshot>
<para>
- On selecting the database type, the appropriate SQL will appear in the <guilabel>SQL for creation</guilabel> text box; this can be edited by the user,
- or saved to a text file by clicking <guibutton>Save SQL</guibutton>. In the latter case, the database
- must be created using the administrative functions provided by the database system.
+ On selecting the database type, the appropriate SQL will appear in the
+ <guilabel>SQL for creation</guilabel> text box; this can be edited by the user, or
+ saved to a text file by clicking <guibutton>Save SQL</guibutton>. In the latter
+ case, the database must be created using the administrative functions provided by
+ the database system.
</para>
+
<para>
- If after editing the text in the dialog, you want &kmymoney; to create the database,
- you will need to complete the other fields in the dialog, as detailed in <link
- linkend="details.database.selectdatabase">Creating a Database</link> above,
- and click <guibutton>Create Tables</guibutton>. Note that, except in the case of
- SQLite, you will need either to include a suitable <literal>CREATE DATABASE</literal> statement
- as the first command, or have previously issued such a command externally to &kmymoney;.
+ If after editing the text in the dialog, you want &kmymoney; to create the
+ database, you will need to complete the other fields in the dialog, as detailed in
+ <link linkend="details.database.selectdatabase">Creating a Database</link> above,
+ and click <guibutton>Create Tables</guibutton>. Note that, except in the case of
+ SQLite, you will need either to include a suitable <literal>CREATE
+ DATABASE</literal> statement as the first command, or have previously issued such a
+ command externally to &kmymoney;. <!-- FIXME: to KMM or to the RDBMS? -->
</para>
</sect3>
-<sect3>
-<title>Warning</title>
+<sect3><title>Warning</title>
+
<para>
- You should be very careful editing the definitions of any of the basic tables or views
- (those with names beginning with '<literal>kmm</literal>'). Some changes,
- such as increasing the length of an integer field, may have little impact, but you should not
- remove or change the sequence of any fields, or &kmymoney; may refuse to function, or may corrupt your data.
+ You should be very careful editing the definitions of any of the basic tables or
+ views (those with names beginning with '<literal>kmm</literal>'.) Some changes,
+ such as increasing the length of an integer field, may have little impact, but you
+ should not remove or change the sequence of any fields, or &kmymoney; may refuse to
+ function, or may corrupt your data.
</para>
+
<para>
- Whilst adding or removing indexes may improve performance, you should also be aware that the opposite
- may happen. Some knowledge of the internal operation of &kmymoney; may help to get the
- best performance in these circumstances.
+ While adding or removing indexes may improve performance, you should also be aware
+ that the opposite may happen. Some knowledge of the internal operation of
+ &kmymoney; may help to get the best performance in these circumstances.
</para>
</sect3>
-
</sect2>
-<sect2>
-<title>Encryption</title>
+<sect2><title>Encryption</title>
<para>
Encryption of data in your database is not currently supported.
diff --git a/doc/details-formats.docbook b/doc/details-formats.docbook
index 8affaf8c9..dee886deb 100644
--- a/doc/details-formats.docbook
+++ b/doc/details-formats.docbook
@@ -3,9 +3,10 @@
<chapterinfo>
<authorgroup>
<author> &Thomas.Baumgart; &Thomas.Baumgart.mail; </author>
+ <author> &Jack.H.Ostroff; &Jack.H.Ostroff.mail; </author>
</authorgroup>
- <date>2014-08-30</date>
- <releaseinfo>4.7.01</releaseinfo>
+ <date>2023-11-25</date>
+ <releaseinfo>5.2</releaseinfo>
</chapterinfo>
<title>File Formats</title>
@@ -13,62 +14,67 @@
<!-- FIXME: be sure to have a better explanation of the Backup command, including
mounting the directory. Can also use OS specifics, especially about folder
mounting on Windows. -->
-
<para>
Unless you choose to use a <link linkend="details.database">relational
- database</link>, &kmymoney; will store all your financial information in a file
- ending in <filename class="extension">.kmy</filename>. Also, when you launch
- &kmymoney;, unless you use a <link linkend="firsttime.launch">command line
- option</link> that tells it not to do so, it will open the last file it had open.
- However, it is important to know that there is actually more than one type of file
- &kmymoney; can use to hold your financial data.
+ database</link>, &kmymoney; will store all your financial information in a file.
+ Most commonly, the file name will end in <filename
+ class="extension">.kmy</filename>. Also, when you launch &kmymoney;, unless you
+ use a <link linkend="firsttime.launch">command line option</link> that tells it not
+ to do so, it will open the last file it had open. However, it is important to know
+ that there is actually more than one type of file &kmymoney; can use to hold your
+ financial data.
</para>
<para>
- This chapter describes the formats in which &kmymoney; stores its data in
- permanent form on the user's storage device. In general, &kmymoney; stores its
- information in form of an &XML; document. Depending on the actual format, this
- &XML; document will be written:
+ This chapter describes the file formats in which &kmymoney; can store its data in
+ permanent form on the user's storage device. It also discusses backing up your data.
+</para>
-<itemizedlist>
- <listitem><para>as a <link linkend="details.formats.plain">plain text
- file</link> encoded in UTF-8,</para></listitem>
+<sect1><title>Data File formats</title>
+
+<para>
+ In general, &kmymoney; stores its
+ information in form of an &XML; document. Depending on the actual format, which is
+ set in &kmymoney;'s configuration, this &XML; document will be written:
+
+ <itemizedlist>
+ <listitem><para>as a plain text file, encoded in UTF-8,</para></listitem>
- <listitem><para>as a <link linkend="details.formats.compressed">compressed
- file</link> using GZIP compression,</para></listitem>
+ <listitem><para>as a compressed file, using GZIP compression,</para></listitem>
- <listitem><para>as an <link linkend="details.formats.encrypted">encrypted
- file</link> using GPG encryption, or</para></listitem>
+ <listitem><para>as an encrypted file, using GPG encryption, or</para></listitem>
- <listitem><para>as an <link linkend="details.formats.anonymous">anonymous
- plain text file</link> encoded in UTF-8 but with all your personal data
- scrambled.</para></listitem>
-</itemizedlist>
+ <listitem>
+ <para>
+ as an anonymous plain text file, encoded in UTF-8 but with all your personal data scrambled.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ Each of these is described in more detail in the following sections.
</para>
-<sect1 id="details.formats.plain">
-<title>Plain text file</title>
+<sect2 id="details.formats.plain"><title>Plain text file</title>
<para>
This is the most space consuming format supported, as no compression is
- performed. It is not intended for normal use, and is provided to support
- debugging purposes and the capability to modify the file manually. If you end
+ performed. It is not intended for normal use, and is provided to support
+ debugging purposes and the capability to modify the file manually. If you end
a filename in <filename class="extension">.xml</filename>, the file will be
stored in this format.
+<!-- FIXME: should this caution really be within the above <para>? -->
<caution>
<para>
- Manual modification of the file is not recommended to the normal user, and
- should only be performed if the internal working of &kmymoney; is fully
- understood or if instructions from the developers tell you what to do. Don't
- blame the &kmymoney; developers if you screw up your data: You have been
- warned!
+ Manual modification of the file is not recommended to the normal user, and should
+ only be performed if the internal working of &kmymoney; is fully understood or if
+ instructions from the developers tell you what to do. Don't blame the &kmymoney;
+ developers if you screw up your data: You have been warned!
</para>
</caution>
</para>
-</sect1>
+</sect2>
-<sect1 id="details.formats.compressed">
-<title>GZIP-compressed file</title>
+<sect2 id="details.formats.compressed"><title>GZIP-compressed file</title>
<para>
This is the normal format used by &kmymoney; when you store a file with the
extension <filename class="extension">.kmy</filename>.
@@ -76,130 +82,256 @@
<note>
<para>
- If <link linkend="details.formats.encrypted">encryption</link> has been
- selected, the file will be stored encrypted.
+ If <link linkend="details.formats.encrypted">encryption</link> has been selected
+ in the configuration, the file will be stored encrypted, as described in the next
+ section.
</para>
</note>
<para>
If you want to look at the contents of a GZIP compressed file, rename it to a
- filename ending in <filename class="extension">.gz</filename> (⪚,
- rename <filename>myfinances.kmy</filename>
- to <filename>myfinances.kmy.gz</filename>), then use <command>gunzip</command>
- to uncompress the file and look at it. You don't have to compress it before
- loading it into &kmymoney; the next time, because &kmymoney; can read the
- uncompressed data as well. Nevertheless, if you save it thereafter, it will be
- saved compressed again. Use the <link linkend="details.formats.plain"><filename
- class="extension">.xml</filename></link> extension to write it in uncompressed
- format.
+ filename ending in <filename class="extension">.gz</filename> (⪚, rename
+ <filename>myfinances.kmy</filename> to <filename>myfinances.kmy.gz</filename>),
+ then use <command>gunzip</command> to uncompress the file and look at it. You
+ don't have to compress it before loading it into &kmymoney; the next time, because
+ &kmymoney; can read the uncompressed data as well. Nevertheless, if you save it
+ thereafter, it will be saved compressed again. Use the <link
+ linkend="details.formats.plain"><filename class="extension">.xml</filename></link>
+ extension to write it in uncompressed format.
</para>
-</sect1>
+</sect2>
-<sect1 id="details.formats.encrypted">
-<title>GPG-encrypted file</title>
+<sect2 id="details.formats.encrypted"><title>GPG-encrypted file</title>
<para>
Using the GPG-encrypted file format is a very secure method of storing your
- personal finance data on your storage device. When &kmymoney; has been
- instructed through the settings dialog to store your data encrypted, it will
- cipher the data using GPG and the key you provided before actually storing
- it. When opening an encrypted file, you have to provide the passphrase
- necessary to open your keyring. The encrypted file itself will be stored in
- GPG's <emphasis>&ASCII; armored</emphasis> format.
+ personal finance data on your storage device. When &kmymoney; has been instructed
+ through the settings dialog to store your data encrypted, it will cipher the data
+ using GPG and the key you provided before actually storing it. When opening an
+ encrypted file, you have to provide the passphrase necessary to open your keyring.
+ The encrypted file itself will be stored in GPG's <emphasis>&ASCII;
+ armored</emphasis> format.
<note>
<para>
- When using GPG encryption, GPG also compresses the file, so no extra
+ When using GPG encryption, GPG also compresses the file using gzip, so no extra
compression is necessary.
</para>
</note>
</para>
-<sect2 id="details.formats.encrypted.gpgkeys">
-<title>GPG-Keys</title>
+<sect3 id="details.formats.encrypted.gpgkeys"><title>GPG-Keys</title>
<para>
If you have not done so already for mail encryption, you need to generate a
- key-pair in order to use the GPG encryption feature of
- &kmymoney;. Also, <application>GPG</application> must be installed on your
- system.
+ key-pair in order to use the GPG encryption feature of &kmymoney;. Also,
+ <application>GPG</application> must be installed on your system.
</para>
<para>
- The details about how to generate a key-pair and how to take care of it are
- beyond the scope of this document. A Mini Howto on this subject can be found
- at <ulink url="https://www.gnupg.org/documentation/howtos.en.html">https://www.gnupg.org/documentation/howtos.en.html</ulink>.
+ The details about how to generate a key-pair and how to take care of it are beyond
+ the scope of this document. A Mini Howto on this subject can be found at <ulink
+ url="https://www.gnupg.org/documentation/howtos.en.html">https://www.gnupg.org/documentation/howtos.en.html</ulink>.
+ The web sites of most &Linux; distributions also contain instructions on using GPG
+ in that distribution.
</para>
-</sect2>
+</sect3>
-<sect2 id="details.formats.encrypted.keysettings">
-<title>Setting the keys in &kmymoney;</title>
-<para>
- On the encryption page of the settings dialog, there is a drop down
- list where you can select the key that should be used for encryption and
- decryption. Additionally you can find a field where you can enter the
- key-id of a key not in the listbox. You can use either the key-id, the
- email address associated with this key, or any other valid GPG key
- identification as the value for this field. When you enter the key-id,
- &kmymoney; will check its validity and display a green LED icon in the
- dialog if a key is found.
+<sect3 id="details.formats.encrypted.keysettings"><title>Setting the keys in &kmymoney;</title>
+<para>
+ On the encryption page of the settings dialog, there is a drop down list where you
+ can select the key that should be used for encryption and decryption.
+ Additionally, there is a field where you can enter the key-id of a key not in the
+ listbox. You can use either the key-id, the email address associated with this
+ key, or any other valid GPG key identification as the value for this field. When
+ you enter the key-id, &kmymoney; will check its validity and display a green LED
+ icon in the dialog if a key is found.
<caution>
<para>
- Make sure you have both the public and the private key for this id. If you
- do not own the private key for the id entered, you will not be able to
- open the file again.
+ Make sure you have both the public and the private key for this id. If you do
+ not own the private key for the id entered, you will not be able to open the
+ file again.
</para>
</caution>
</para>
-</sect2>
+</sect3>
-<sect2 id="details.formats.encrypted.recoverkey">
-<title>The &kmymoney; recover key</title>
+<sect3 id="details.formats.encrypted.recoverkey"><title>The &kmymoney; recover key</title>
<para>
Also on this page of the settings dialog you have the choice of selecting
- supplemental encryption with the &kmymoney; recover key. This option is
- available to you if that key is stored in your <application>GPG</application>
- keyring. Selecting this option will allow you to recover your data even in the
- case you lose your own private key. This is possible because the data is not
- only encrypted for your own key, but also for the &kmymoney; recover key. This
- key is only available to selected &kmymoney; developers (at the time of
- writing only to the author). As of the release of &kmymoney; version 4.7, the
- recover key is set to expire on 3 January 2015.
+ supplemental encryption with the &kmymoney; recover key. This option is available
+ to you if that key is stored in your <application>GPG</application> keyring.
+ Selecting this option will allow you to recover your data even in the case you lose
+ your own private key. This is possible because the data is not only encrypted for
+ your own key, but also for the &kmymoney; recover key. This key is only available
+ to selected &kmymoney; developers (at the time of writing only to the author.) As
+ of the November 2023, the recover key is set to expire on 7 January 2024.
+ <!-- should we specify that you import the PUBLIC key? More generally, should we
+ give more details on how to find and import the recovery key? -->
</para>
<para>
- Under normal circumstances, you will open/save/close your file as usual. In
- the abnormal case of loss of your key, you have the chance to contact one of
- the developers who has access to the &kmymoney; recover key and request help
- to recover your data. You may contact the developers via email to the
- &kmymoney; developer mailing list at &devlist;.
+ Under normal circumstances, you will open/save/close your file as usual. In the
+ abnormal case of loss of your key, you have the chance to contact one of the
+ developers who has access to the &kmymoney; recover key and request help to recover
+ your data. You may contact the developers via email to the &kmymoney; developer
+ mailing list at &devlist;.
+</para>
+
+<para>
+ To get the recovery key, go to <ulink url="https://kmymoney.org/recovery.html"> The
+ KMyMoney recovery key</ulink> page of the &kmymoney; web site. Copy and save the
+ <quote>PGP PUBLIC KEY BLOCK</quote> (including the <quote>BEGIN</quote> and
+ <quote>END</quote> lines) to a text file and then import
+</para>
+</sect3>
+</sect2>
+
+<sect2 id="details.formats.anonymous"><title>Anonymous file</title>
+<para>
+ This format is not intended to be used for normal data storage. It is supported so
+ that in case of a problem, you can supply the &kmymoney; development team with your
+ file without disclosing any of the confidential details in your financial data.
+ For example, it changes institution, account, payee, and category names to strings
+ such as "I000001" and "A000001"; it makes similar changes to all data such as
+ account numbers, and it also randomly changes the amounts of transactions.
+</para>
+
+<para>
+ If instructed by the developers, use the <guimenuitem>Save as...</guimenuitem> menu
+ item to store your data in anonymous format by selecting <literal
+ role="filter">Anonymous files</literal> as the filter. This also changes the file
+ extension to <filename class="extension">.anon.xml</filename>.
+</para>
+
+<para>
+ To verify that your problem still exists, reload this anonymized file and try to
+ duplicate your problem. If the problem is still present, send the file to the
+ developer mailing list at &devlist; for further investigation. If the problem does
+ not show ... well, I don't want to think about this scenario right now.
</para>
</sect2>
</sect1>
-<sect1 id="details.formats.anonymous">
-<title>Anonymous file</title>
+<sect1 id="details.formats.backup"><title>Backup</title>
+
+<para>
+ We will not attempt here to convince you that making backup copies of your data is
+ an extremely good idea; hopefully you are already convinced of that. This section
+ describes three ways to do this, and you can use any one, two, or even all three of
+ them. Note that this is about backing up a data file; if you use an SQL backend to
+ store your data, see the documentation for that database system for instructions on
+ making backups.
+</para>
+
+<sect2><title>Backup file location</title>
+
<para>
- This format is not intended to be used for normal data storage. It is
- supported so that in case of a problem, you can supply the &kmymoney;
- development team with your file without disclosing any of the confidential
- details in your financial data. For example, it changes institution, account,
- payee, and category names to strings such as "I000001" and "A000001", it makes
- similar changes to all data such as account numbers, and it also randomly
- changes the amounts of transactions.
+ If you need a backup copy of your data to confirm some aspect of your finances at a
+ previous point in time, or to revert to an earlier state, such as to undo importing
+ a lot of data to the wrong account, it doesn't matter whether the backup copy is
+ local or stored elsewhere, such as on an attached network drive. However, if you
+ need a backup to recover from loss of data if you disk drive failed, for example,
+ it is essential that the backup is <emphasis>not</emphasis> on the same drive as
+ your primary data file. In case of a larger disaster, such as a house fire, you
+ would need a backup copy stored in a fireproof safe or at a physically different
+ location. Please keep this in mind as you establish your backup strategy.
</para>
+</sect2>
+
+<sect2><title>Autosave</title>
+<!-- FIXME: if the Settings chapter is modified to include screenshots and
+ descriptions of all config settings, this section will move there, and just be
+ referred to here. -->
<para>
- If instructed by the developers, use the <guimenuitem>Save as...</guimenuitem>
- menu item to store your data in anonymous format by selecting <literal
- role="filter">Anonymous files</literal> as the filter. This also changes the
- file extension to <filename class="extension">.anon.xml</filename>.
+ On the &kmymoney; configuration dialog, General section, Global tab, the upper
+ <guilabel>Autosave options</guilabel> area allows you to control this feature. An
+ autosave file is just a copy of your data file. The main point of these is that
+ they are automatically created, according to the configuration settings, so you do
+ not need to remember to take any action. Any autosave files created will be in the
+ same directory as the data file currently open.
</para>
+<itemizedlist>
+ <listitem>
+ <para>
+ Autosave periodically: if this checkbox is ticked, then &kmymoney; will create
+ a new autosave file at the interval specified by the
+ <guilabel>minutes</guilabel> field.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Autosave when file is modified upon close: if this checkbox is ticked, then
+ when you close the program, &kmymoney; will create an autosave file if the data
+ has changed at all since it was last saved.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Number of backups to keep (0=off): This sets the number of autosave files
+ &kmymoney; will create. If your data file is MyFinances.kmy, then when an
+ autosave file is created, it will be called MyFinances.kmy.1~. Any existing
+ autosave files will have their number increased by 1, up to the specified
+ number.
+ </para>
+ </listitem>
+</itemizedlist>
+</sect2>
+
+<sect2><title>File copy</title>
+
<para>
- To verify that your problem still exists, reload this anonymized
- file and try to duplicate your problem. If the problem is still
- present, send the file to the developer mailing list at &devlist;
- for further investigation. If the problem does not show ... well, I
- don't want to think about this scenario right now.
+ Unless you are using SQL storage, your data may be compressed, and it may be
+ encrypted, but is kept in a regular file. Whenever you save your data with the
+ <menuchoice><guimenu>File</guimenu><guimenuitem>Save</guimenuitem></menuchoice>
+ menu item, it writes all your data to a file, replacing the previous version. The
+ most straightforward way of backing up your data is by making a copy of that file.
+ A single copy can even have the same file name if it is in a different folder than
+ your original file, but if you are going to keep multiple copies, it makes sense to
+ include some version of the current date and time in each file name. You can save
+ these to a network drive, or to a USB storage device, or even to an optical device.
+ The primary downside of this method is that you need to keep track of all the
+ backups, but it does provide the most flexibility.
</para>
+</sect2>
+
+<sect2><title>Backup command</title>
+
+<para>
+ To make things a bit easier, you can select the <menuchoice>
+ <guimenu>File</guimenu> <guimenuitem>Backup</guimenuitem> </menuchoice> menu item.
+
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="file-backup.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <phrase>file backup</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+
+ When you click <guibutton>OK</guibutton> &kmymoney; will create a copy of your data
+ file, with the date (formatted as YYYY-MM-DD) appended to the name. Note that this
+ means only one backup per day can be created by this method.
+</para>
+
+<para>
+ &kmymoney; will save this file to the directory specified in the <guilabel>Mount
+ Point</guilabel> field. You can either manually type the full path to the
+ directory or click <guibutton>Choose...</guibutton> and navigate to it using the
+ file browser. The directory can be on a local storage device or it can be a
+ network folder.
+</para>
+
+<para>
+ If the specified directory is actually a mount point for a storage device that is
+ not always mounted, you can check the <guilabel>Mount this directory before backing
+ up</guilabel> checkbox. Do not use this for a regular network file share which is
+ always moutned.
+</para>
+</sect2>
</sect1>
</chapter>
-
diff --git a/doc/details-settings.docbook b/doc/details-settings.docbook
index 88aab4ef2..9fc74c901 100644
--- a/doc/details-settings.docbook
+++ b/doc/details-settings.docbook
@@ -13,10 +13,10 @@
<title>&kmymoney; Settings</title>
<para>
- The settings described below modify the behavior of &kmymoney;, allowing you to
- customize it to meet the needs of your unique financial affairs, and to modify its
- look and feel to match your personality. These settings can be changed through
- the <menuchoice> <guimenu>Settings</guimenu> <guimenuitem>Configure
+ The settings described in this chapter modify the behavior of &kmymoney;, allowing
+ you to customize it to meet the needs of your unique financial affairs, and to
+ modify its look and feel to match your personality. These settings can be changed
+ through the <menuchoice> <guimenu>Settings</guimenu> <guimenuitem>Configure
&kmymoney;...</guimenuitem> </menuchoice> menu item or by using the keyboard
shortcut <keycombo action="simul">&Ctrl; &Shift;<keycap>,</keycap></keycombo>. In
order for any changes to take effect the <guibutton>Apply</guibutton> button must
diff --git a/doc/file-backup.png b/doc/file-backup.png
new file mode 100644
index 000000000..30fd2491d
Binary files /dev/null and b/doc/file-backup.png differ
More information about the kde-doc-english
mailing list