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
