modules/dbscripts/README.txt

QUICK START GUIDE

    1. Place the dbscripts folder wherever you would wish.  It is recomended to 
       not put it in your web root 
       (not your modules folder)

    2. Create the folder database dumps will save to
       (default setting in config.inc.example is as a sibling to the dbscripts 
       folder)

    3. Copy config.inc.example and PostMergeInstructions.txt.example preserving 
       their filenames and removing ".example".  Configure them as needed

    4. If you are using CCK and wish to merge schema changes:

        i. Apply the patch for content_copy to allow modifying existing fields

        ii. Within your Drupal website, enable the content_copy module and export
            all of your content types.  Save the export data in files


EXAMPLE USES

Dumping the database:
    Development: ./dbscripts/dump.php
    Production: ./dbscripts/dump.php production min
    Last Merge: ./dbscripts/dump.php last-merge

Restoring a database file:
    Development: ./dbscripts/restore.php
    Production: ./dbscripts/restore.php production min
    Last Merge: ./dbscripts/restore.php last-merge

Merging the databases:
    First bring last-merge.sql and production.sql to the same schema as 
        development.sql
    ./dbscripts/merge.php

Use 'help' for more information.  ie: ./dbscripts/dump.php help


REQUIRES

GNU Diff3 is required.  Sun Solaris, for example, uses their own version of 
Diff3 which is incompatible with how it is used in this script.


MERGING DATABASES 

Warning:  Merged databases should only be deployed on stable and secure versions 
ready for public consumption!

Once you've done a merge that you are going to keep, you must deploy it to 
production.  You can perform merges for testing purposes, but if you're going to 
commit a merged version to your version control system, you must also deploy it 
to production or they will become out of sync.  Feel free to try to fix this 
restriction.


MERGING CONCEPT

There are three databases stored: development, production and last-merge.  
Development and production are obvious to their namesake, while last-merge 
records the last point the two branches were identical.  Since both development 
and production have the power to create, delete and modify content, the 
last-merge database serves as a starting point to compare with so the difference 
between an addition and a subtraction can be tracked.

This script assumes the production database will only track content and users.  
Other changes made and stored in the production database will be lost.  
Additionally, user data is not preserved in development after a merge.

Manually, the developer will first bring the merged and production databases to 
have the same structure as the development database (for the data we're 
concerned with, anyways) by loading each database into MySQL, accessing the site 
through a web browser, running update.php and importing the content types in 
dbscripts/content_types.  

Running the merge script will then strip all content and user data from the 
development database and use that as a "skeleton."  User data is taken from 
production and appended to the skeleton.  Data to be merged is taken from all 
three databases and the production and development data compared with the 
last-merge data. Diff3 is run on the three versions creating a newly merged data 
set.  That data is then appended to the end of the database structure skeleton. 

Finally, to have all data in the right spot and ordered in the right way in the 
dump files (so a proper difference can be created for version control), the 
databases are restored and dumped again.  

The production database is loaded into MySQL by the end of this script. That 
version should be tested thoroughly.


NOTE: To ensure there is no conflict between development database and production 
      database, the table structures must be the same for all three databases 
      first.  To do this, follow these steps:

        NOTE: Perform these steps in a staging area!

        1) SVN update all files
        2) Restore the last-merge database: 
               ./dbscripts/restore.php last-merge min
        3) Run update.php as needed
        4) Import content_type data as needed
        5) Dump database: 
               ./dbscripts/dump.php last-merge
        6) Restore the production database: 
               ./dbscripts/restore.php production min
        7) Repeat steps 3 & 4 for the production database
        8) Dump database: ./dbscripts/dump.php production min
        9) Run the merge script
        10) Test, test, test, then test some more
        11) Commit

WARNING: When merging development and production databases, the development will 
         lose all user data and be replaced with production user data.  Also 
         keep aware it merges ALL nodes, so nodes created for testing purposes 
         should first be deleted or unpublished before merging the databases.


MERGE CONFLICTS

Conflicts can happen, and the script will catch it allow you to resolve the 
conflicts manually.  The most frequent causes of conflicts are:

  * Editing the same peice of content on both development and production.  Just 
    try not to do that.  To gracfually resolve that issue, though, keep 
    revisions enabled and install the diff module.  During conflict resolution 
    you will only have to pick which revision to use in the node table - both 
    revisions will be preserved, it's just choosing which one will be visible.  
    Then you can go in and see the conflicts using the diff module between the 
    two revisions.

  * Scaling issues.  Changes to the same area (such as new nodes) in both 
    versions in which at least one version had a lot of changes.  Apparently, 
    Diff will only figure it out so much, and then just gives up and declares it 
    a conflict.  Normally it's just a matter of removing the conflict markers.

  * Upgrading the schema incorrectly.  If there are A LOT of conflicts, it's 
    probably a schema issue.  Ensure that you performed the schema synching 
    correctly and that each column is in the correct order.

Perform test merges frequently so you'll be kept informed of any issues as they 
come up.  

Use the PostMergeInstructions.txt file to track what actions need to be 
performed after merging.  Example:  You added a new CCK field, and then have to 
enable a setting in a node that was added during the production branch.  Or, you 
edited the same node on both development and production and you note it needs to 
be manually resolved.
1	QUICK START GUIDE
2
3	1. Place the dbscripts folder wherever you would wish. It is recomended to
4	not put it in your web root
5	(not your modules folder)
6
7	2. Create the folder database dumps will save to
8	(default setting in config.inc.example is as a sibling to the dbscripts
9	folder)
10
11	3. Copy config.inc.example and PostMergeInstructions.txt.example preserving
12	their filenames and removing ".example". Configure them as needed
13
14	4. If you are using CCK and wish to merge schema changes:
15
16	i. Apply the patch for content_copy to allow modifying existing fields
17
18	ii. Within your Drupal website, enable the content_copy module and export
19	all of your content types. Save the export data in files
20
21
22	EXAMPLE USES
23
24	Dumping the database:
25	Development: ./dbscripts/dump.php
26	Production: ./dbscripts/dump.php production min
27	Last Merge: ./dbscripts/dump.php last-merge
28
29	Restoring a database file:
30	Development: ./dbscripts/restore.php
31	Production: ./dbscripts/restore.php production min
32	Last Merge: ./dbscripts/restore.php last-merge
33
34	Merging the databases:
35	First bring last-merge.sql and production.sql to the same schema as
36	development.sql
37	./dbscripts/merge.php
38
39	Use 'help' for more information. ie: ./dbscripts/dump.php help
40
41
42	REQUIRES
43
44	GNU Diff3 is required. Sun Solaris, for example, uses their own version of
45	Diff3 which is incompatible with how it is used in this script.
46
47
48	MERGING DATABASES
49
50	Warning: Merged databases should only be deployed on stable and secure versions
51	ready for public consumption!
52
53	Once you've done a merge that you are going to keep, you must deploy it to
54	production. You can perform merges for testing purposes, but if you're going to
55	commit a merged version to your version control system, you must also deploy it
56	to production or they will become out of sync. Feel free to try to fix this
57	restriction.
58
59
60	MERGING CONCEPT
61
62	There are three databases stored: development, production and last-merge.
63	Development and production are obvious to their namesake, while last-merge
64	records the last point the two branches were identical. Since both development
65	and production have the power to create, delete and modify content, the
66	last-merge database serves as a starting point to compare with so the difference
67	between an addition and a subtraction can be tracked.
68
69	This script assumes the production database will only track content and users.
70	Other changes made and stored in the production database will be lost.
71	Additionally, user data is not preserved in development after a merge.
72
73	Manually, the developer will first bring the merged and production databases to
74	have the same structure as the development database (for the data we're
75	concerned with, anyways) by loading each database into MySQL, accessing the site
76	through a web browser, running update.php and importing the content types in
77	dbscripts/content_types.
78
79	Running the merge script will then strip all content and user data from the
80	development database and use that as a "skeleton." User data is taken from
81	production and appended to the skeleton. Data to be merged is taken from all
82	three databases and the production and development data compared with the
83	last-merge data. Diff3 is run on the three versions creating a newly merged data
84	set. That data is then appended to the end of the database structure skeleton.
85
86	Finally, to have all data in the right spot and ordered in the right way in the
87	dump files (so a proper difference can be created for version control), the
88	databases are restored and dumped again.
89
90	The production database is loaded into MySQL by the end of this script. That
91	version should be tested thoroughly.
92
93
94	NOTE: To ensure there is no conflict between development database and production
95	database, the table structures must be the same for all three databases
96	first. To do this, follow these steps:
97
98	NOTE: Perform these steps in a staging area!
99
100	1) SVN update all files
101	2) Restore the last-merge database:
102	./dbscripts/restore.php last-merge min
103	3) Run update.php as needed
104	4) Import content_type data as needed
105	5) Dump database:
106	./dbscripts/dump.php last-merge
107	6) Restore the production database:
108	./dbscripts/restore.php production min
109	7) Repeat steps 3 & 4 for the production database
110	8) Dump database: ./dbscripts/dump.php production min
111	9) Run the merge script
112	10) Test, test, test, then test some more
113	11) Commit
114
115	WARNING: When merging development and production databases, the development will
116	lose all user data and be replaced with production user data. Also
117	keep aware it merges ALL nodes, so nodes created for testing purposes
118	should first be deleted or unpublished before merging the databases.
119
120
121	MERGE CONFLICTS
122
123	Conflicts can happen, and the script will catch it allow you to resolve the
124	conflicts manually. The most frequent causes of conflicts are:
125
126	* Editing the same peice of content on both development and production. Just
127	try not to do that. To gracfually resolve that issue, though, keep
128	revisions enabled and install the diff module. During conflict resolution
129	you will only have to pick which revision to use in the node table - both
130	revisions will be preserved, it's just choosing which one will be visible.
131	Then you can go in and see the conflicts using the diff module between the
132	two revisions.
133
134	* Scaling issues. Changes to the same area (such as new nodes) in both
135	versions in which at least one version had a lot of changes. Apparently,
136	Diff will only figure it out so much, and then just gives up and declares it
137	a conflict. Normally it's just a matter of removing the conflict markers.
138
139	* Upgrading the schema incorrectly. If there are A LOT of conflicts, it's
140	probably a schema issue. Ensure that you performed the schema synching
141	correctly and that each column is in the correct order.
142
143	Perform test merges frequently so you'll be kept informed of any issues as they
144	come up.
145
146	Use the PostMergeInstructions.txt file to track what actions need to be
147	performed after merging. Example: You added a new CCK field, and then have to
148	enable a setting in a node that was added during the production branch. Or, you
149	edited the same node on both development and production and you note it needs to
150	be manually resolved.