Skip to content

Savepoint API

Jump to bottom Edit New page
Oxford Harrison edited this page Nov 12, 2024 · 6 revisions

DOCS • API

Savepoint is the object representation of a database's savepoint. This object is obtained either via database.savepoint() or via a CREATE, ALTER, or DROP operation.

See content

savepoint.id:

The UUID associated with the savepoint. 
savepoint.id: (UUID, readonly)

⚽️ Usage:

const savepoint = await client.database('test_db').savepoint();
console.log(savepoint.id); // f740d66a-df5f-4a34-a281-8ef3ba6fe754

savepoint.databaseTag():

The subject database's generic identifier that transcends name changes. 
savepoint.databaseTag(): (string, readonly)

⚽️ Usage:

Consider a database's generic identifier before and after a name change:

// Before name change
const savepoint = await client.database('test_db').savepoint();
console.log(savepoint.databaseTag()); // db:18m6z
// Name change
await client.alterDatabase('test_db', schema => schema.name('test_db_new'));
// Now even after name change
const savepoint = await client.database('test_db_new').savepoint();
console.log(savepoint.databaseTag()); // db:18m6z

savepoint.versionTag():

The savepoint's version tag. 
savepoint.versionTag(): (number, readonly)

⚽️ Usage:

// Version 1
const savepoint = await client.createDatabase({
    name: 'test_db',
    tables: [{
        name: 'test_tbl1',
        columns: [],
    }]
});
console.log(savepoint.versionTag()); // 1
// Version 2
const savepoint = await client.database('test_db').createTable({
    name: 'test_tbl2',
    columns: [],
});
console.log(savepoint.versionTag()); // 2
// Version 2 currently
const savepoint = await client.database('test_db').savepoint();
console.log(savepoint.versionTag()); // 2

savepoint.versionMax():

The database's peak version regardless of its current rollback level. 
savepoint.versionMax(): (number, readonly)

⚽️ Usage:

const savepoint = await client.database('test_db').savepoint();
console.log(savepoint.versionTag()); // 2
console.log(savepoint.versionMax()); // 2
await savepoint.rollback();
const savepoint = await client.database('test_db').savepoint();
console.log(savepoint.versionTag()); // 1
console.log(savepoint.versionMax()); // 2

savepoint.commitDesc():

The commitDesc() for the changes associated with the savepoint. 
savepoint.commitDesc(): (string, readonly)

⚽️ Usage:

const savepoint = await client.database('test_db').createTable({
    name: 'test_tbl2',
    columns: [],
}, { commitDesc(): 'Create test_tbl2' });
console.log(savepoint.commitDesc()); // Create test_tbl2
const savepoint = await client.database('test_db').savepoint();
console.log(savepoint.commitDesc()); // Create test_tbl2

savepoint.commitDate():

The savepoint's creation date. 
savepoint.commitDate(): (Date, readonly)

⚽️ Usage:

const savepoint = await client.database('test_db').savepoint();
console.log(savepoint.commitDate()); // 2024-07-20T15:31:06.096Z

savepoint.rollbackDate():

The savepoint's rollback date. 
savepoint.rollbackDate(): (Date, readonly)

⚽️ Usage:

const savepoint = await client.database('test_db').createTable({
    name: 'test_tbl2',
    columns: [],
}, { commitDesc(): 'Create test_tbl2' });
console.log(savepoint.rollbackDate()); // null
await savepoint.rollback();
console.log(savepoint.rollbackDate()); // 2024-07-20T15:31:06.096Z
// Find the same savepoint with a forward lookup
const savepoint = await client.database('test_db').savepoint({ direction: 'forward' });
console.log(savepoint.rollbackDate()); // 2024-07-20T15:31:06.096Z

savepoint.restorePreview():

A single-word summary of the effect that rolling back to this savepoint will have on subject DB. 
savepoint.restorePreview(): (string, readonly)

⚽️ Usage:

Will rolling back to given savepoint mean dropping or re-creating the subject database?:

For a create operation...

const savepoint = await client.createDatabase('test_db', { descripton: 'Create db' });

Rolling back will mean dropping the DB:

console.log(savepoint.descripton); // Create db
console.log(savepoint.restorePreview()); // DROP
// Drop DB
console.log(savepoint.restorePreview()); // DROP
await savepoint.rollback();

Having rolled back, rolling forward will mean a re-creation of the DB:

// Find the same savepoint with a forward lookup
const savepoint = await client.database('test_db').savepoint({ direction: 'forward' });
// Now rolling back will mean re-creating the DB
console.log(savepoint.descripton); // Create db
console.log(savepoint.restorePreview()); // CREATE

But note that table-level create/drop operations always only have an ALTER effect on parent DB:

// Create table - which translates to a DB "alter" operation
const savepoint = await client.database('test_db').createTable({
    name: 'test_tbl2',
    columns: [],
}, { commitDesc(): 'Create test_tbl2' });
// Rolling back will mean dropping the table - which will still translate to a DB "alter" operation
console.log(savepoint.descripton); // Create test_tbl2
console.log(savepoint.restorePreview()); // ALTER
// Drop DB
await savepoint.rollback();
console.log(savepoint.restorePreview()); // ALTER
// Find the same savepoint with a forward lookup
const savepoint = await client.database('test_db').savepoint({ direction: 'forward' });
// Now rolling back will mean re-creating the table - which will still translate to a DB "alter" operation
console.log(savepoint.descripton); // Create test_tbl2
console.log(savepoint.restorePreview()); // ALTER

savepoint.rollbackQuery:

A query preview of the rollback. 
savepoint.rollbackQuery: ({ toString(): string }, readonly)

⚽️ Usage:

You get a query instance that is toString()able:

For a create operation...

const savepoint = await client.createDatabase('test_db', { descripton: 'Create db' });

Rolling back will mean dropping the DB:

console.log(savepoint.rollbackQuery.toString()); // DROP SCHEMA test_db CASCADE

savepoint.isNextRestorePoint():

Check if the savepoint is the next actual point in time for the database. 
savepoint.isNextRestorePoint(): Promise<boolean>

⚙️ Spec:

  • Return value: boolean.

⚽️ Usage:

For a new operation, that would be true:

const dbCreationSavepoint = await client.createDatabase('test_db');
console.log(await dbCreationSavepoint.isNextRestorePoint()); // true

But after having performed more operations, that wouldn't be:

const tblCreationSavepoint = await client.database('test_db').createTable({
    name: 'test_tbl',
    columns: [{
        name: 'id',
        type: 'int'
    }]
});
console.log(await tblCreationSavepoint.isNextRestorePoint()); // true
console.log(await dbCreationSavepoint.isNextRestorePoint()); // false

Rollback table creation and test dbCreationSavepoint's position again:

await tblCreationSavepoint.rollback();
console.log(await tblCreationSavepoint.isNextRestorePoint()); // false
console.log(await dbCreationSavepoint.isNextRestorePoint()); // true

savepoint.rollback():

Rollback all changes associated with given savepoint. 
savepoint.rollback(): Promise<boolean>

⚙️ Spec:

  • Return value: boolean.

⚽️ Usage:

Create database and rollback:

// Create DB
const savepoint = await client.createDatabase('test_db', { descripton: 'Create db' });
// Roll back - which means drop the DB
await savepoint.rollback();

Undo the rollback; i.e. roll forward:

// Find the same savepoint with a forward lookup
const savepoint = await client.database('test_db').savepoint({ direction: 'forward' });
// Roll back - which means re-create the DB
await savepoint.rollback();

savepoint.jsonfy():

Get a plain object representation of the savepoint. 
savepoint.jsonfy(): object

⚙️ Spec:

  • Return value: an object of the form { id: string, name: string, databaseTag(): string, versionTag(): number, versionMax(): number, cursor: string, commitDesc(): string, commitDate(): Date, rollbackDate(): Date | null }.

⚽️ Usage:

const savepoint = await client.createDatabase('test_db', { descripton: 'Create db' });
console.log(savepoint.jsonfy());

savepoint.schema():

Get the subject DB's schema snapshot at this point in time. 
savepoint.schema(): object

⚙️ Spec:

  • Return value: an object corresponding to DatabaseSchemaSpec (in schema.json).

⚽️ Usage:

const savepoint = await client.database('test_db').createTable({
    name: 'test_tbl',
    columns: [{
        name: 'id',
        type: 'int'
    }]
});
console.log(savepoint.schema());
const savepoint = await client.database('test_db').savepoint();
await savepoint.schema();

savepoint.name():

Get the subject database's name. 
savepoint.name(postRollback?: boolean): string

⚙️ Spec:

  • postRollback (boolean, optional): in case a name change was captured in the savepoint, whether to return the database's post-rollback name. Otherwise the database's active, pre-rollback name is returned.
  • Return value: the database name.

⚽️ Usage:

// Name change
const savepoint = await client.alterDatabase('test_db', schema => schema.name('test_db_new'));
// The database's active, pre-rollback name
console.log(savepoint.name()); // test_db_new
// The database's post-rollback name
console.log(savepoint.name(true)); // test_db
Add a custom footer
Add a custom sidebar
Clone this wiki locally