]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | // Copyright (c) 2011-present, Facebook, Inc. All rights reserved. |
2 | // This source code is licensed under the BSD-style license found in the | |
3 | // LICENSE file in the root directory of this source tree. An additional grant | |
4 | // of patent rights can be found in the PATENTS file in the same directory. | |
5 | package org.rocksdb; | |
6 | ||
7 | import java.util.List; | |
8 | ||
9 | /** | |
10 | * BackupEngine allows you to backup | |
11 | * and restore the database | |
12 | * | |
13 | * Be aware, that `new BackupEngine` takes time proportional to the amount | |
14 | * of backups. So if you have a slow filesystem to backup (like HDFS) | |
15 | * and you have a lot of backups then restoring can take some time. | |
16 | * That's why we recommend to limit the number of backups. | |
17 | * Also we recommend to keep BackupEngine alive and not to recreate it every | |
18 | * time you need to do a backup. | |
19 | */ | |
20 | public class BackupEngine extends RocksObject implements AutoCloseable { | |
21 | ||
22 | protected BackupEngine(final long nativeHandle) { | |
23 | super(nativeHandle); | |
24 | } | |
25 | ||
26 | /** | |
27 | * Opens a new Backup Engine | |
28 | * | |
29 | * @param env The environment that the backup engine should operate within | |
30 | * @param options Any options for the backup engine | |
31 | * | |
32 | * @return A new BackupEngine instance | |
33 | * @throws RocksDBException thrown if the backup engine could not be opened | |
34 | */ | |
35 | public static BackupEngine open(final Env env, | |
36 | final BackupableDBOptions options) throws RocksDBException { | |
37 | return new BackupEngine(open(env.nativeHandle_, options.nativeHandle_)); | |
38 | } | |
39 | ||
40 | /** | |
41 | * Captures the state of the database in the latest backup | |
42 | * | |
43 | * Just a convenience for {@link #createNewBackup(RocksDB, boolean)} with | |
44 | * the flushBeforeBackup parameter set to false | |
45 | * | |
46 | * @param db The database to backup | |
47 | * | |
48 | * Note - This method is not thread safe | |
49 | * | |
50 | * @throws RocksDBException thrown if a new backup could not be created | |
51 | */ | |
52 | public void createNewBackup(final RocksDB db) throws RocksDBException { | |
53 | createNewBackup(db, false); | |
54 | } | |
55 | ||
56 | /** | |
57 | * Captures the state of the database in the latest backup | |
58 | * | |
59 | * @param db The database to backup | |
60 | * @param flushBeforeBackup When true, the Backup Engine will first issue a | |
61 | * memtable flush and only then copy the DB files to | |
62 | * the backup directory. Doing so will prevent log | |
63 | * files from being copied to the backup directory | |
64 | * (since flush will delete them). | |
65 | * When false, the Backup Engine will not issue a | |
66 | * flush before starting the backup. In that case, | |
67 | * the backup will also include log files | |
68 | * corresponding to live memtables. The backup will | |
69 | * always be consistent with the current state of the | |
70 | * database regardless of the flushBeforeBackup | |
71 | * parameter. | |
72 | * | |
73 | * Note - This method is not thread safe | |
74 | * | |
75 | * @throws RocksDBException thrown if a new backup could not be created | |
76 | */ | |
77 | public void createNewBackup( | |
78 | final RocksDB db, final boolean flushBeforeBackup) | |
79 | throws RocksDBException { | |
80 | assert (isOwningHandle()); | |
81 | createNewBackup(nativeHandle_, db.nativeHandle_, flushBeforeBackup); | |
82 | } | |
83 | ||
84 | /** | |
85 | * Gets information about the available | |
86 | * backups | |
87 | * | |
88 | * @return A list of information about each available backup | |
89 | */ | |
90 | public List<BackupInfo> getBackupInfo() { | |
91 | assert (isOwningHandle()); | |
92 | return getBackupInfo(nativeHandle_); | |
93 | } | |
94 | ||
95 | /** | |
96 | * <p>Returns a list of corrupted backup ids. If there | |
97 | * is no corrupted backup the method will return an | |
98 | * empty list.</p> | |
99 | * | |
100 | * @return array of backup ids as int ids. | |
101 | */ | |
102 | public int[] getCorruptedBackups() { | |
103 | assert(isOwningHandle()); | |
104 | return getCorruptedBackups(nativeHandle_); | |
105 | } | |
106 | ||
107 | /** | |
108 | * <p>Will delete all the files we don't need anymore. It will | |
109 | * do the full scan of the files/ directory and delete all the | |
110 | * files that are not referenced.</p> | |
111 | * | |
112 | * @throws RocksDBException thrown if error happens in underlying | |
113 | * native library. | |
114 | */ | |
115 | public void garbageCollect() throws RocksDBException { | |
116 | assert(isOwningHandle()); | |
117 | garbageCollect(nativeHandle_); | |
118 | } | |
119 | ||
120 | /** | |
121 | * Deletes old backups, keeping just the latest numBackupsToKeep | |
122 | * | |
123 | * @param numBackupsToKeep The latest n backups to keep | |
124 | * | |
125 | * @throws RocksDBException thrown if the old backups could not be deleted | |
126 | */ | |
127 | public void purgeOldBackups( | |
128 | final int numBackupsToKeep) throws RocksDBException { | |
129 | assert (isOwningHandle()); | |
130 | purgeOldBackups(nativeHandle_, numBackupsToKeep); | |
131 | } | |
132 | ||
133 | /** | |
134 | * Deletes a backup | |
135 | * | |
136 | * @param backupId The id of the backup to delete | |
137 | * | |
138 | * @throws RocksDBException thrown if the backup could not be deleted | |
139 | */ | |
140 | public void deleteBackup(final int backupId) throws RocksDBException { | |
141 | assert (isOwningHandle()); | |
142 | deleteBackup(nativeHandle_, backupId); | |
143 | } | |
144 | ||
145 | /** | |
146 | * Restore the database from a backup | |
147 | * | |
148 | * IMPORTANT: if options.share_table_files == true and you restore the DB | |
149 | * from some backup that is not the latest, and you start creating new | |
150 | * backups from the new DB, they will probably fail! | |
151 | * | |
152 | * Example: Let's say you have backups 1, 2, 3, 4, 5 and you restore 3. | |
153 | * If you add new data to the DB and try creating a new backup now, the | |
154 | * database will diverge from backups 4 and 5 and the new backup will fail. | |
155 | * If you want to create new backup, you will first have to delete backups 4 | |
156 | * and 5. | |
157 | * | |
158 | * @param backupId The id of the backup to restore | |
159 | * @param dbDir The directory to restore the backup to, i.e. where your | |
160 | * database is | |
161 | * @param walDir The location of the log files for your database, | |
162 | * often the same as dbDir | |
163 | * @param restoreOptions Options for controlling the restore | |
164 | * | |
165 | * @throws RocksDBException thrown if the database could not be restored | |
166 | */ | |
167 | public void restoreDbFromBackup( | |
168 | final int backupId, final String dbDir, final String walDir, | |
169 | final RestoreOptions restoreOptions) throws RocksDBException { | |
170 | assert (isOwningHandle()); | |
171 | restoreDbFromBackup(nativeHandle_, backupId, dbDir, walDir, | |
172 | restoreOptions.nativeHandle_); | |
173 | } | |
174 | ||
175 | /** | |
176 | * Restore the database from the latest backup | |
177 | * | |
178 | * @param dbDir The directory to restore the backup to, i.e. where your | |
179 | * database is | |
180 | * @param walDir The location of the log files for your database, often the | |
181 | * same as dbDir | |
182 | * @param restoreOptions Options for controlling the restore | |
183 | * | |
184 | * @throws RocksDBException thrown if the database could not be restored | |
185 | */ | |
186 | public void restoreDbFromLatestBackup( | |
187 | final String dbDir, final String walDir, | |
188 | final RestoreOptions restoreOptions) throws RocksDBException { | |
189 | assert (isOwningHandle()); | |
190 | restoreDbFromLatestBackup(nativeHandle_, dbDir, walDir, | |
191 | restoreOptions.nativeHandle_); | |
192 | } | |
193 | ||
194 | private native static long open(final long env, | |
195 | final long backupableDbOptions) throws RocksDBException; | |
196 | ||
197 | private native void createNewBackup(final long handle, final long dbHandle, | |
198 | final boolean flushBeforeBackup) throws RocksDBException; | |
199 | ||
200 | private native List<BackupInfo> getBackupInfo(final long handle); | |
201 | ||
202 | private native int[] getCorruptedBackups(final long handle); | |
203 | ||
204 | private native void garbageCollect(final long handle) throws RocksDBException; | |
205 | ||
206 | private native void purgeOldBackups(final long handle, | |
207 | final int numBackupsToKeep) throws RocksDBException; | |
208 | ||
209 | private native void deleteBackup(final long handle, final int backupId) | |
210 | throws RocksDBException; | |
211 | ||
212 | private native void restoreDbFromBackup(final long handle, final int backupId, | |
213 | final String dbDir, final String walDir, final long restoreOptionsHandle) | |
214 | throws RocksDBException; | |
215 | ||
216 | private native void restoreDbFromLatestBackup(final long handle, | |
217 | final String dbDir, final String walDir, final long restoreOptionsHandle) | |
218 | throws RocksDBException; | |
219 | ||
220 | @Override protected final native void disposeInternal(final long handle); | |
221 | } |