Constraint

Data Structures
struct	db_foreign_key_def_t
	Foreign key definition. More...
Defines
#define	DB_FK_ACTION_RESTRICT   0
#define	DB_FK_ACTION_CASCADE   1
#define	DB_FK_ACTION_SETNULL   2
#define	DB_FK_ACTION_SETDEFAULT   3
#define	DB_FK_MATCH_SIMPLE   0
#define	DB_FK_MATCH_FULL   1
#define	DB_FK_NOT_DEFERRABLE   0
#define	DB_FK_DEFERRABLE   1
#define	DB_FK_CHECK_IMMEDIATE   0
#define	DB_FK_CHECK_DEFERRED   1
Functions
db_result_t	db_tabledef_set_foreign_key_count (db_tabledef_t *, db_len_t)
db_result_t	db_tabledef_set_foreign_keys (db_tabledef_t *, const db_foreign_key_def_t *, db_len_t nkeys)
db_result_t	db_tabledef_set_foreign_key (db_tabledef_t *, db_len_t index, const db_foreign_key_def_t *)
db_result_t	db_create_foreign_key (db_t, const db_objname_t *table, const db_foreign_key_def_t *)
db_result_t	db_drop_foreign_key (db_t, const db_objname_t *table, const db_objname_t *fkname)

---

Detailed Description

Foreign key constraints enforce relationships between tables.

---

Define Documentation

#define DB_FK_ACTION_RESTRICT   0

The action cannot be performed on a referenced row.

Examples:

phonebook_c_schema.c.

#define DB_FK_ACTION_CASCADE   1

When the action is performed on key fields in a referenced row, the same action is performed on referencing rows.

#define DB_FK_ACTION_SETNULL   2

When the action is performed on key fields in a referenced row, all foreign key fields in referencing rows are set to null.

#define DB_FK_ACTION_SETDEFAULT   3

When the action is performed on key fields in a referenced row, all foreign key fields in referencing rows are set to their default values.

#define DB_FK_MATCH_SIMPLE   0

Some fields in the foreign key may be null, in which case no row is referenced.

A row is only referenced when no foreign key fields are null.

Examples:

phonebook_c_schema.c.

#define DB_FK_MATCH_FULL   1

All fields in the foreign key must be null if any are null.

A row is only referenced when no foreign key fields are null.

#define DB_FK_NOT_DEFERRABLE   0

The foreign key cannot be deferred until commit.

Examples:

phonebook_c_schema.c.

#define DB_FK_DEFERRABLE   1

The foreign key can be deferred until commit.

This feature is not implemented.

#define DB_FK_CHECK_IMMEDIATE   0

The foreign key is initially immediate.

Examples:

phonebook_c_schema.c.

#define DB_FK_CHECK_DEFERRED   1

The foreign key is initially deferred.

This feature is not implemented.

---

Function Documentation

db_result_t db_tabledef_set_foreign_key_count	(	db_tabledef_t *	tdef,
		db_len_t	nkeys
	)

Set the number of foreign keys in a table definition.

Parameters:

tdef	Table definition.
nkeys	Number of foreign keys to store in the table definition.

Use db_tabledef_destroy to reclaim memory allocated by this function. If the foreign_keys member is not NULL and nforeign_keys > 0, existing definitions will be copied into the new buffer.

If the number of foreign key definitions is increased by this function, each is initialized with default values.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

See also:

db_tabledef_init, db_tabledef_destroy,
get_db_error, clear_db_error, Error Handling

db_result_t db_tabledef_set_foreign_keys	(	db_tabledef_t *	tdef,
		const db_foreign_key_def_t *	keys,
		db_len_t	nkeys
	)

Copy a list of foreign keys into a table defininforeign_keystion.

Parameters:

tdef	Table definition.
keys	An array of foreign key definitions.
nkeys	Number of foreign keys in the array.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

See also:

db_tabledef_init, db_tabledef_destroy,
get_db_error, clear_db_error, Error Handling

db_result_t db_tabledef_set_foreign_key	(	db_tabledef_t *	tdef,
		db_len_t	nindex,
		const db_foreign_key_def_t *	fkdef
	)

Set a foreign key in a table definition.

Parameters:

tdef	Table definition.
nindex	The array index of the foreign key definition to set.
fkdef	The foreign key definition to copy.

Precondition:

index must be less than tdef->nforeign_keys. Either use

db_tabledef_set_foreign_key_count or set tdef->foreign_keys to a large

enough buffer.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

See also:

db_tabledef_set_foreign_key_count,
get_db_error, clear_db_error, Error Handling

db_result_t db_create_foreign_key	(	db_t	hdb,
		const db_objname_t *	table,
		const db_foreign_key_def_t *	fkdef
	)

Create a foreign key constraint in a database.

Parameters:

hdb	Database handle.
table	The referencing table.nforeign_keys
fkdef	The foreign key definition.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

Invariant:

No transaction is active on hdb.

See also:

get_db_error, clear_db_error, Error Handling

db_result_t db_drop_foreign_key	(	db_t	hdb,
		const db_objname_t *	table,
		const db_objname_t *	fkname
	)

Drop a foreign key constraint from a database.

Parameters:

hdb	Database handle.
table	Name of the referencing table.
fkname	Name of the foreign key.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

Invariant:

No transaction is active on hdb.

See also:

get_db_error, clear_db_error, Error Handling