1 /* Copyright (c) 2003-2007 MySQL AB
3 This program is free software; you can redistribute it and/or modify
4 it under the terms of the GNU General Public License as published by
5 the Free Software Foundation; version 2 of the License.
7 This program is distributed in the hope that it will be useful,
8 but WITHOUT ANY WARRANTY; without even the implied warranty of
9 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
10 GNU General Public License for more details.
12 You should have received a copy of the GNU General Public License
13 along with this program; if not, write to the Free Software
14 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA */
16 #ifndef NdbDictionary_H
17 #define NdbDictionary_H
19 #include <ndb_types.h>
22 struct charset_info_st
;
23 typedef struct charset_info_st CHARSET_INFO
;
26 * @class NdbDictionary
27 * @brief Data dictionary class
29 * The preferred and supported way to create and drop tables and indexes
30 * in ndb is through the
31 * MySQL Server (see MySQL reference Manual, section MySQL Cluster).
33 * Tables and indexes that are created directly through the
35 * can not be viewed from the MySQL Server.
36 * Dropping indexes directly via the NdbApi will cause inconsistencies
37 * if they were originally created from a MySQL Cluster.
39 * This class supports schema data enquiries such as:
40 * -# Enquiries about tables
41 * (Dictionary::getTable, Table::getNoOfColumns,
42 * Table::getPrimaryKey, and Table::getNoOfPrimaryKeys)
43 * -# Enquiries about indexes
44 * (Dictionary::getIndex, Index::getNoOfColumns,
45 * and Index::getColumn)
47 * This class supports schema data definition such as:
48 * -# Creating tables (Dictionary::createTable) and table columns
49 * -# Dropping tables (Dictionary::dropTable)
50 * -# Creating secondary indexes (Dictionary::createIndex)
51 * -# Dropping secondary indexes (Dictionary::dropIndex)
53 * NdbDictionary has several help (inner) classes to support this:
54 * -# NdbDictionary::Dictionary the dictionary handling dictionary objects
55 * -# NdbDictionary::Table for creating tables
56 * -# NdbDictionary::Column for creating table columns
57 * -# NdbDictionary::Index for creating secondary indexes
59 * See @ref ndbapi_simple_index.cpp for details of usage.
63 NdbDictionary() {} /* Remove gcc warning */
66 * @brief Meta information about a database object (a table, index, etc)
70 Object() {} /* Remove gcc warning */
71 virtual ~Object() {} /* Remove gcc warning */
76 New
, ///< The object only exist in memory and
77 ///< has not been created in the NDB Kernel
78 Changed
, ///< The object has been modified in memory
79 ///< and has to be commited in NDB Kernel for
80 ///< changes to take effect
81 Retrieved
, ///< The object exist and has been read
82 ///< into main memory from NDB Kernel
83 Invalid
, ///< The object has been invalidated
84 ///< and should not be used
85 Altered
///< Table has been altered in NDB kernel
86 ///< but is still valid for usage
90 * Get status of object
92 virtual Status
getObjectStatus() const = 0;
95 * Get version of object
97 virtual int getObjectVersion() const = 0;
99 virtual int getObjectId() const = 0;
105 TypeUndefined
= 0, ///< Undefined
106 SystemTable
= 1, ///< System table
107 UserTable
= 2, ///< User table (may be temporary)
108 UniqueHashIndex
= 3, ///< Unique un-ordered hash index
109 OrderedIndex
= 6, ///< Non-unique ordered index
110 HashIndexTrigger
= 7, ///< Index maintenance, internal
111 IndexTrigger
= 8, ///< Index maintenance, internal
112 SubscriptionTrigger
= 9,///< Backup or replication, internal
113 ReadOnlyConstraint
= 10,///< Trigger, internal
114 Tablespace
= 20, ///< Tablespace
115 LogfileGroup
= 21, ///< Logfile group
116 Datafile
= 22, ///< Datafile
117 Undofile
= 23 ///< Undofile
124 StateUndefined
= 0, ///< Undefined
125 StateOffline
= 1, ///< Offline, not usable
126 StateBuilding
= 2, ///< Building, not yet usable
127 StateDropping
= 3, ///< Offlining or dropping, not usable
128 StateOnline
= 4, ///< Online, usable
129 StateBackup
= 5, ///< Online, being backuped, usable
130 StateBroken
= 9 ///< Broken, should be dropped and re-created
137 StoreUndefined
= 0, ///< Undefined
138 StoreNotLogged
= 1, ///< Object or data deleted on system restart
139 StorePermanent
= 2 ///< Permanent. logged to disk
143 * Type of fragmentation.
145 * This parameter specifies how data in the table or index will
146 * be distributed among the db nodes in the cluster.<br>
147 * The bigger the table the more number of fragments should be used.
148 * Note that all replicas count as same "fragment".<br>
149 * For a table, default is FragAllMedium. For a unique hash index,
150 * default is taken from underlying table and cannot currently
154 FragUndefined
= 0, ///< Fragmentation type undefined or default
155 FragSingle
= 1, ///< Only one fragment
156 FragAllSmall
= 2, ///< One fragment per node, default
157 FragAllMedium
= 3, ///< two fragments per node
158 FragAllLarge
= 4, ///< Four fragments per node.
165 class Dictionary
; // Forward declaration
167 class ObjectId
: public Object
174 * Get status of object
176 virtual Status
getObjectStatus() const;
179 * Get version of object
181 virtual int getObjectVersion() const;
183 virtual int getObjectId() const;
186 friend class NdbDictObjectImpl
;
187 class NdbDictObjectImpl
& m_impl
;
190 class Table
; // forward declaration
191 class Tablespace
; // forward declaration
192 // class NdbEventOperation; // forward declaration
196 * @brief Represents a column in an NDB Cluster table
198 * Each column has a type. The type of a column is determined by a number
199 * of type specifiers.
200 * The type specifiers are:
202 * - Array length or max length
203 * - Precision and scale (not used yet)
204 * - Character set for string types
205 * - Inline and part sizes for blobs
207 * Types in general correspond to MySQL types and their variants.
208 * Data formats are same as in MySQL. NDB API provides no support for
209 * constructing such formats. NDB kernel checks them however.
214 * The builtin column types
217 Undefined
= NDB_TYPE_UNDEFINED
, ///< Undefined
218 Tinyint
= NDB_TYPE_TINYINT
, ///< 8 bit. 1 byte signed integer, can be used in array
219 Tinyunsigned
= NDB_TYPE_TINYUNSIGNED
, ///< 8 bit. 1 byte unsigned integer, can be used in array
220 Smallint
= NDB_TYPE_SMALLINT
, ///< 16 bit. 2 byte signed integer, can be used in array
221 Smallunsigned
= NDB_TYPE_SMALLUNSIGNED
, ///< 16 bit. 2 byte unsigned integer, can be used in array
222 Mediumint
= NDB_TYPE_MEDIUMINT
, ///< 24 bit. 3 byte signed integer, can be used in array
223 Mediumunsigned
= NDB_TYPE_MEDIUMUNSIGNED
,///< 24 bit. 3 byte unsigned integer, can be used in array
224 Int
= NDB_TYPE_INT
, ///< 32 bit. 4 byte signed integer, can be used in array
225 Unsigned
= NDB_TYPE_UNSIGNED
, ///< 32 bit. 4 byte unsigned integer, can be used in array
226 Bigint
= NDB_TYPE_BIGINT
, ///< 64 bit. 8 byte signed integer, can be used in array
227 Bigunsigned
= NDB_TYPE_BIGUNSIGNED
, ///< 64 Bit. 8 byte signed integer, can be used in array
228 Float
= NDB_TYPE_FLOAT
, ///< 32-bit float. 4 bytes float, can be used in array
229 Double
= NDB_TYPE_DOUBLE
, ///< 64-bit float. 8 byte float, can be used in array
230 Olddecimal
= NDB_TYPE_OLDDECIMAL
, ///< MySQL < 5.0 signed decimal, Precision, Scale
231 Olddecimalunsigned
= NDB_TYPE_OLDDECIMALUNSIGNED
,
232 Decimal
= NDB_TYPE_DECIMAL
, ///< MySQL >= 5.0 signed decimal, Precision, Scale
233 Decimalunsigned
= NDB_TYPE_DECIMALUNSIGNED
,
234 Char
= NDB_TYPE_CHAR
, ///< Len. A fixed array of 1-byte chars
235 Varchar
= NDB_TYPE_VARCHAR
, ///< Length bytes: 1, Max: 255
236 Binary
= NDB_TYPE_BINARY
, ///< Len
237 Varbinary
= NDB_TYPE_VARBINARY
, ///< Length bytes: 1, Max: 255
238 Datetime
= NDB_TYPE_DATETIME
, ///< Precision down to 1 sec (sizeof(Datetime) == 8 bytes )
239 Date
= NDB_TYPE_DATE
, ///< Precision down to 1 day(sizeof(Date) == 4 bytes )
240 Blob
= NDB_TYPE_BLOB
, ///< Binary large object (see NdbBlob)
241 Text
= NDB_TYPE_TEXT
, ///< Text blob
242 Bit
= NDB_TYPE_BIT
, ///< Bit, length specifies no of bits
243 Longvarchar
= NDB_TYPE_LONGVARCHAR
, ///< Length bytes: 2, little-endian
244 Longvarbinary
= NDB_TYPE_LONGVARBINARY
, ///< Length bytes: 2, little-endian
245 Time
= NDB_TYPE_TIME
, ///< Time without date
246 Year
= NDB_TYPE_YEAR
, ///< Year 1901-2155 (1 byte)
247 Timestamp
= NDB_TYPE_TIMESTAMP
///< Unix time
251 * Array type specifies internal attribute format.
253 * - ArrayTypeFixed is stored as fixed number of bytes. This type
254 * is fastest to access but can waste space.
256 * - ArrayTypeVar is stored as variable number of bytes with a fixed
257 * overhead of 2 bytes.
259 * Default is ArrayTypeVar for Var* types and ArrayTypeFixed for
260 * others. The default is normally ok.
263 ArrayTypeFixed
= NDB_ARRAYTYPE_FIXED
, // 0 length bytes
264 ArrayTypeShortVar
= NDB_ARRAYTYPE_SHORT_VAR
, // 1 length bytes
265 ArrayTypeMediumVar
= NDB_ARRAYTYPE_MEDIUM_VAR
// 2 length bytes
269 * Storage type specifies whether attribute is stored in memory or
270 * on disk. Default is memory. Disk attributes are potentially
271 * much slower to access and cannot be indexed in version 5.1.
274 StorageTypeMemory
= NDB_STORAGETYPE_MEMORY
,
275 StorageTypeDisk
= NDB_STORAGETYPE_DISK
285 * @return Name of the column
287 const char* getName() const;
290 * Get if the column is nullable or not
292 bool getNullable() const;
295 * Check if column is part of primary key
297 bool getPrimaryKey() const;
300 * Get number of column (horizontal position within table)
302 int getColumnNo() const;
304 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
305 int getAttrId() const;
309 * Check if column is equal to some other column
310 * @param column Column to compare with
311 * @return true if column is equal to some other column otherwise false.
313 bool equal(const Column
& column
) const;
316 /** @} *******************************************************************/
318 * @name Get Type Specifiers
325 Type
getType() const;
328 * Get precision of column.
329 * @note Only applicable for decimal types
331 int getPrecision() const;
334 * Get scale of column.
335 * @note Only applicable for decimal types
337 int getScale() const;
340 * Get length for column
341 * Array length for column or max length for variable length arrays.
343 int getLength() const;
346 * For Char or Varchar or Text, get MySQL CHARSET_INFO. This
347 * specifies both character set and collation. See get_charset()
348 * etc in MySQL. (The cs is not "const" in MySQL).
350 CHARSET_INFO
* getCharset() const;
354 * For blob, get "inline size" i.e. number of initial bytes
355 * to store in table's blob attribute. This part is normally in
356 * main memory and can be indexed and interpreted.
358 int getInlineSize() const;
361 * For blob, get "part size" i.e. number of bytes to store in
362 * each tuple of the "blob table". Can be set to zero to omit parts
363 * and to allow only inline bytes ("tinyblob").
365 int getPartSize() const;
368 * For blob, set or get "stripe size" i.e. number of consecutive
369 * <em>parts</em> to store in each node group.
371 int getStripeSize() const;
374 * Get size of element
379 * Check if column is part of partition key
381 * A <em>partition key</em> is a set of attributes which are used
382 * to distribute the tuples onto the NDB nodes.
383 * The partition key uses the NDB Cluster hashing function.
385 * An example where this is useful is TPC-C where it might be
386 * good to use the warehouse id and district id as the partition key.
387 * This would place all data for a specific district and warehouse
388 * in the same database node.
390 * Locally in the fragments the full primary key
391 * will still be used with the hashing algorithm.
393 * @return true then the column is part of
396 bool getPartitionKey() const;
397 #ifndef DOXYGEN_SHOULD_SKIP_DEPRECATED
398 inline bool getDistributionKey() const { return getPartitionKey(); };
401 ArrayType
getArrayType() const;
402 StorageType
getStorageType() const;
404 /** @} *******************************************************************/
408 * @name Column creation
411 * These operations should normally not be performed in an NbdApi program
412 * as results will not be visable in the MySQL Server
418 * @param name Name of column
420 Column(const char * name
= "");
423 * @param column Column to be copied
425 Column(const Column
& column
);
430 * @param name Name of the column
432 int setName(const char * name
);
435 * Set whether column is nullable or not
437 void setNullable(bool);
440 * Set that column is part of primary key
442 void setPrimaryKey(bool);
446 * @param type Type of column
448 * @note setType resets <em>all</em> column attributes
449 * to (type dependent) defaults and should be the first
450 * method to call. Default type is Unsigned.
452 void setType(Type type
);
455 * Set precision of column.
456 * @note Only applicable for decimal types
458 void setPrecision(int);
461 * Set scale of column.
462 * @note Only applicable for decimal types
467 * Set length for column
468 * Array length for column or max length for variable length arrays.
470 void setLength(int length
);
473 * For Char or Varchar or Text, get MySQL CHARSET_INFO. This
474 * specifies both character set and collation. See get_charset()
475 * etc in MySQL. (The cs is not "const" in MySQL).
477 void setCharset(CHARSET_INFO
* cs
);
480 * For blob, get "inline size" i.e. number of initial bytes
481 * to store in table's blob attribute. This part is normally in
482 * main memory and can be indexed and interpreted.
484 void setInlineSize(int size
);
487 * For blob, get "part size" i.e. number of bytes to store in
488 * each tuple of the "blob table". Can be set to zero to omit parts
489 * and to allow only inline bytes ("tinyblob").
491 void setPartSize(int size
);
494 * For blob, get "stripe size" i.e. number of consecutive
495 * <em>parts</em> to store in each node group.
497 void setStripeSize(int size
);
501 * @see getPartitionKey
503 * @param enable If set to true, then the column will be part of
506 void setPartitionKey(bool enable
);
507 #ifndef DOXYGEN_SHOULD_SKIP_DEPRECATED
508 inline void setDistributionKey(bool enable
)
509 { setPartitionKey(enable
); };
512 void setArrayType(ArrayType type
);
513 void setStorageType(StorageType type
);
515 /** @} *******************************************************************/
517 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
518 const Table
* getBlobTable() const;
520 void setAutoIncrement(bool);
521 bool getAutoIncrement() const;
522 void setAutoIncrementInitialValue(Uint64 val
);
523 int setDefaultValue(const char*);
524 const char* getDefaultValue() const;
526 static const Column
* FRAGMENT
;
527 static const Column
* FRAGMENT_FIXED_MEMORY
;
528 static const Column
* FRAGMENT_VARSIZED_MEMORY
;
529 static const Column
* ROW_COUNT
;
530 static const Column
* COMMIT_COUNT
;
531 static const Column
* ROW_SIZE
;
532 static const Column
* RANGE_NO
;
533 static const Column
* DISK_REF
;
534 static const Column
* RECORDS_IN_RANGE
;
535 static const Column
* ROWID
;
536 static const Column
* ROW_GCI
;
537 static const Column
* ANY_VALUE
;
538 static const Column
* COPY_ROWID
;
540 int getSizeInBytes() const;
544 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
545 friend class NdbRecAttr
;
546 friend class NdbColumnImpl
;
548 class NdbColumnImpl
& m_impl
;
549 Column(NdbColumnImpl
&);
550 Column
& operator=(const Column
&);
553 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
557 typedef Column Attribute
;
561 * @brief Represents a table in NDB Cluster
563 * <em>TableSize</em><br>
564 * When calculating the data storage one should add the size of all
565 * attributes (each attributeconsumes at least 4 bytes) and also an overhead
566 * of 12 byte. Variable size attributes (not supported yet) will have a
567 * size of 12 bytes plus the actual data storage parts where there is an
568 * additional overhead based on the size of the variable part.<br>
569 * An example table with 5 attributes:
570 * one 64 bit attribute, one 32 bit attribute,
571 * two 16 bit attributes and one array of 64 8 bits.
572 * This table will consume
573 * 12 (overhead) + 8 + 4 + 2*4 (4 is minimum) + 64 = 96 bytes per record.
574 * Additionally an overhead of about 2 % as page headers and waste should
575 * be allocated. Thus, 1 million records should consume 96 MBytes
576 * plus the overhead 2 MByte and rounded up to 100 000 kBytes.<br>
579 class Table
: public Object
{
582 * Single user mode specifies access rights to table during single user mode
584 enum SingleUserMode
{
585 SingleUserModeLocked
= NDB_SUM_LOCKED
,
586 SingleUserModeReadOnly
= NDB_SUM_READONLY
,
587 SingleUserModeReadWrite
= NDB_SUM_READ_WRITE
598 const char * getName() const;
603 int getTableId() const;
606 * Get column definition via name.
607 * @return null if none existing name
609 const Column
* getColumn(const char * name
) const;
612 * Get column definition via index in table.
613 * @return null if none existing name
615 Column
* getColumn(const int attributeId
);
618 * Get column definition via name.
619 * @return null if none existing name
621 Column
* getColumn(const char * name
);
624 * Get column definition via index in table.
625 * @return null if none existing name
627 const Column
* getColumn(const int attributeId
) const;
629 /** @} *******************************************************************/
636 * If set to false, then the table is a temporary
637 * table and is not logged to disk.
639 * In case of a system restart the table will still
640 * be defined and exist but will be empty.
641 * Thus no checkpointing and no logging is performed on the table.
643 * The default value is true and indicates a normal table
644 * with full checkpointing and logging activated.
646 bool getLogging() const;
649 * Get fragmentation type
651 FragmentType
getFragmentType() const;
654 * Get KValue (Hash parameter.)
655 * Only allowed value is 6.
656 * Later implementations might add flexibility in this parameter.
658 int getKValue() const;
661 * Get MinLoadFactor (Hash parameter.)
662 * This value specifies the load factor when starting to shrink
664 * It must be smaller than MaxLoadFactor.
665 * Both these factors are given in percentage.
667 int getMinLoadFactor() const;
670 * Get MaxLoadFactor (Hash parameter.)
671 * This value specifies the load factor when starting to split
672 * the containers in the local hash tables.
673 * 100 is the maximum which will optimize memory usage.
674 * A lower figure will store less information in each container and thus
675 * find the key faster but consume more memory.
677 int getMaxLoadFactor() const;
679 /** @} *******************************************************************/
686 * Get number of columns in the table
688 int getNoOfColumns() const;
691 * Get number of primary keys in the table
693 int getNoOfPrimaryKeys() const;
696 * Get name of primary key
698 const char* getPrimaryKey(int no
) const;
701 * Check if table is equal to some other table
703 bool equal(const Table
&) const;
706 * Get frm file stored with this table
708 const void* getFrmData() const;
709 Uint32
getFrmLength() const;
712 * Get Fragment Data (id, state and node group)
714 const void *getFragmentData() const;
715 Uint32
getFragmentDataLen() const;
718 * Get Range or List Array (value, partition)
720 const void *getRangeListData() const;
721 Uint32
getRangeListDataLen() const;
724 * Get Tablespace Data (id, version)
726 const void *getTablespaceData() const;
727 Uint32
getTablespaceDataLen() const;
729 /** @} *******************************************************************/
732 * @name Table creation
735 * These methods should normally not be used in an application as
736 * the result is not accessible from the MySQL Server
742 * @param name Name of table
744 Table(const char * name
= "");
748 * @param table Table to be copied
750 Table(const Table
& table
);
754 * Assignment operator, deep copy
755 * @param table Table to be copied
757 Table
& operator=(const Table
& table
);
761 * @param name Name of table
763 int setName(const char * name
);
766 * Add a column definition to a table
767 * @note creates a copy
769 int addColumn(const Column
&);
772 * @see NdbDictionary::Table::getLogging.
774 void setLogging(bool);
777 * Set/Get Linear Hash Flag
779 void setLinearFlag(Uint32 flag
);
780 bool getLinearFlag() const;
785 void setFragmentCount(Uint32
);
790 Uint32
getFragmentCount() const;
793 * Set fragmentation type
795 void setFragmentType(FragmentType
);
798 * Set KValue (Hash parameter.)
799 * Only allowed value is 6.
800 * Later implementations might add flexibility in this parameter.
802 void setKValue(int kValue
);
805 * Set MinLoadFactor (Hash parameter.)
806 * This value specifies the load factor when starting to shrink
808 * It must be smaller than MaxLoadFactor.
809 * Both these factors are given in percentage.
811 void setMinLoadFactor(int);
814 * Set MaxLoadFactor (Hash parameter.)
815 * This value specifies the load factor when starting to split
816 * the containers in the local hash tables.
817 * 100 is the maximum which will optimize memory usage.
818 * A lower figure will store less information in each container and thus
819 * find the key faster but consume more memory.
821 void setMaxLoadFactor(int);
823 int setTablespaceName(const char * name
);
824 const char * getTablespaceName() const;
825 int setTablespace(const class Tablespace
&);
826 bool getTablespace(Uint32
*id
= 0, Uint32
*version
= 0) const;
829 * Get table object type
831 Object::Type
getObjectType() const;
836 virtual Object::Status
getObjectStatus() const;
837 void setStatusInvalid() const;
842 virtual int getObjectVersion() const;
845 * Set/Get indicator if default number of partitions is used in table.
847 void setDefaultNoPartitionsFlag(Uint32 indicator
);
848 Uint32
getDefaultNoPartitionsFlag() const;
853 virtual int getObjectId() const;
856 * Set frm file to store with this table
858 int setFrm(const void* data
, Uint32 len
);
861 * Set array of fragment information containing
863 * Node group identity
866 int setFragmentData(const void* data
, Uint32 len
);
869 * Set/Get tablespace names per fragment
871 int setTablespaceNames(const void* data
, Uint32 len
);
872 const void *getTablespaceNames();
873 Uint32
getTablespaceNamesLen() const;
876 * Set tablespace information per fragment
877 * Contains a tablespace id and a tablespace version
879 int setTablespaceData(const void* data
, Uint32 len
);
882 * Set array of information mapping range values and list values
883 * to fragments. This is essentially a sorted map consisting of
884 * pairs of value, fragment identity. For range partitions there is
885 * one pair per fragment. For list partitions it could be any number
886 * of pairs, at least as many as there are fragments.
888 int setRangeListData(const void* data
, Uint32 len
);
891 * Set table object type
893 void setObjectType(Object::Type type
);
896 * Set/Get Maximum number of rows in table (only used to calculate
897 * number of partitions).
899 void setMaxRows(Uint64 maxRows
);
900 Uint64
getMaxRows() const;
903 * Set/Get Minimum number of rows in table (only used to calculate
904 * number of partitions).
906 void setMinRows(Uint64 minRows
);
907 Uint64
getMinRows() const;
910 * Set/Get SingleUserMode
912 void setSingleUserMode(enum SingleUserMode
);
913 enum SingleUserMode
getSingleUserMode() const;
916 /** @} *******************************************************************/
921 void setRowGCIIndicator(bool value
);
922 bool getRowGCIIndicator() const;
924 void setRowChecksumIndicator(bool value
);
925 bool getRowChecksumIndicator() const;
927 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
928 const char *getMysqlName() const;
930 void setStoredTable(bool x
) { setLogging(x
); }
931 bool getStoredTable() const { return getLogging(); }
933 int getRowSizeInBytes() const ;
934 int createTableInDb(Ndb
*, bool existingEqualIsOk
= true) const ;
936 int getReplicaCount() const ;
939 void setTemporary(bool);
942 * Only table with varpart do support online add column
943 * Add property so that table wo/ varsize column(s) still
944 * allocates varpart-ref, so that later online add column is possible
946 bool getForceVarPart() const;
947 void setForceVarPart(bool);
950 * Check if any of column in bitmaps are disk columns
951 * returns bitmap of different columns
952 * bit 0 = atleast 1 pk column is set
953 * bit 1 = atleast 1 disk column set
954 * bit 2 = atleast 1 non disk column set
955 * passing NULL pointer will equal to bitmap with all columns set
957 int checkColumns(const Uint32
* bitmap
, unsigned len_in_bytes
) const;
960 // these 2 are not de-doxygenated
963 * This method is not needed in normal usage.
965 * Compute aggregate data on table being defined. Required for
966 * aggregate methods such as getNoOfPrimaryKeys() to work before
967 * table has been created and retrieved via getTable().
969 * May adjust some column flags. If no PK is so far marked as
970 * distribution key then all PK's will be marked.
972 * Returns 0 on success. Returns -1 and sets error if an
973 * inconsistency is detected.
975 int aggregate(struct NdbError
& error
);
978 * This method is not needed in normal usage.
980 * Validate new table definition before create. Does aggregate()
981 * and additional checks. There may still be errors which are
982 * detected only by NDB kernel at create table.
984 * Create table and retrieve table do validate() automatically.
986 * Returns 0 on success. Returns -1 and sets error if an
987 * inconsistency is detected.
989 int validate(struct NdbError
& error
);
992 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
994 friend class NdbDictionaryImpl
;
995 friend class NdbTableImpl
;
996 friend class NdbEventOperationImpl
;
998 class NdbTableImpl
& m_impl
;
999 Table(NdbTableImpl
&);
1004 * @brief Represents an index in an NDB Cluster
1006 class Index
: public Object
{
1010 * @name Getting Index properties
1015 * Get the name of an index
1017 const char * getName() const;
1020 * Get the name of the table being indexed
1022 const char * getTable() const;
1025 * Get the number of columns in the index
1027 unsigned getNoOfColumns() const;
1029 #ifndef DOXYGEN_SHOULD_SKIP_DEPRECATED
1031 * Get the number of columns in the index
1032 * Depricated, use getNoOfColumns instead.
1034 int getNoOfIndexColumns() const;
1038 * Get a specific column in the index
1040 const Column
* getColumn(unsigned no
) const ;
1042 #ifndef DOXYGEN_SHOULD_SKIP_DEPRECATED
1044 * Get a specific column name in the index
1045 * Depricated, use getColumn instead.
1047 const char * getIndexColumn(int no
) const ;
1051 * Represents type of index
1054 Undefined
= 0, ///< Undefined object type (initial value)
1055 UniqueHashIndex
= 3, ///< Unique un-ordered hash index
1056 ///< (only one currently supported)
1057 OrderedIndex
= 6 ///< Non-unique ordered index
1061 * Get index type of the index
1063 Type
getType() const;
1066 * Check if index is set to be stored on disk
1068 * @return if true then logging id enabled
1070 * @note Non-logged indexes are rebuilt at system restart.
1071 * @note Ordered index does not currently support logging.
1073 bool getLogging() const;
1078 virtual Object::Status
getObjectStatus() const;
1081 * Get object version
1083 virtual int getObjectVersion() const;
1088 virtual int getObjectId() const;
1090 /** @} *******************************************************************/
1093 * @name Index creation
1096 * These methods should normally not be used in an application as
1097 * the result will not be visible from the MySQL Server
1103 * @param name Name of index
1105 Index(const char * name
= "");
1109 * Set the name of an index
1111 int setName(const char * name
);
1114 * Define the name of the table to be indexed
1116 int setTable(const char * name
);
1119 * Add a column to the index definition
1120 * Note that the order of columns will be in
1121 * the order they are added (only matters for ordered indexes).
1123 int addColumn(const Column
& c
);
1126 * Add a column name to the index definition
1127 * Note that the order of indexes will be in
1128 * the order they are added (only matters for ordered indexes).
1130 int addColumnName(const char * name
);
1132 #ifndef DOXYGEN_SHOULD_SKIP_DEPRECATED
1134 * Add a column name to the index definition
1135 * Note that the order of indexes will be in
1136 * the order they are added (only matters for ordered indexes).
1137 * Depricated, use addColumnName instead.
1139 int addIndexColumn(const char * name
);
1143 * Add several column names to the index definition
1144 * Note that the order of indexes will be in
1145 * the order they are added (only matters for ordered indexes).
1147 int addColumnNames(unsigned noOfNames
, const char ** names
);
1149 #ifndef DOXYGEN_SHOULD_SKIP_DEPRECATED
1151 * Add several column names to the index definition
1152 * Note that the order of indexes will be in
1153 * the order they are added (only matters for ordered indexes).
1154 * Depricated, use addColumnNames instead.
1156 int addIndexColumns(int noOfNames
, const char ** names
);
1160 * Set index type of the index
1162 void setType(Type type
);
1165 * Enable/Disable index storage on disk
1167 * @param enable If enable is set to true, then logging becomes enabled
1169 * @see NdbDictionary::Index::getLogging
1171 void setLogging(bool enable
);
1173 #ifndef DOXYGEN_SHOULD_SKIP_DEPRECATED
1174 void setStoredIndex(bool x
) { setLogging(x
); }
1175 bool getStoredIndex() const { return getLogging(); }
1177 bool getTemporary();
1178 void setTemporary(bool);
1181 /** @} *******************************************************************/
1184 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
1185 friend class NdbIndexImpl
;
1186 friend class NdbIndexStat
;
1188 class NdbIndexImpl
& m_impl
;
1189 Index(NdbIndexImpl
&);
1193 * @brief Represents an Event in NDB Cluster
1196 class Event
: public Object
{
1199 * Specifies the type of database operations an Event listens to
1201 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
1202 /** TableEvent must match 1 << TriggerEvent */
1205 TE_INSERT
=1<<0, ///< Insert event on table
1206 TE_DELETE
=1<<1, ///< Delete event on table
1207 TE_UPDATE
=1<<2, ///< Update event on table
1208 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
1209 TE_SCAN
=1<<3, ///< Scan event on table
1210 TE_FIRST_NON_DATA_EVENT
=1<<4,
1212 TE_DROP
=1<<4, ///< Drop of table
1213 TE_ALTER
=1<<5, ///< Alter of table
1214 TE_CREATE
=1<<6, ///< Create of table
1215 TE_GCP_COMPLETE
=1<<7, ///< GCP is complete
1216 TE_CLUSTER_FAILURE
=1<<8, ///< Cluster is unavailable
1217 TE_STOP
=1<<9, ///< Stop of event operation
1218 TE_NODE_FAILURE
=1<<10, ///< Node failed
1219 TE_SUBSCRIBE
=1<<11, ///< Node subscribes
1220 TE_UNSUBSCRIBE
=1<<12, ///< Node unsubscribes
1221 TE_ALL
=0xFFFF ///< Any/all event on table (not relevant when
1222 ///< events are received)
1224 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
1230 _TE_FIRST_NON_DATA_EVENT
=4,
1235 _TE_CLUSTER_FAILURE
=8,
1237 _TE_NODE_FAILURE
=10,
1240 _TE_NUL
=13, // internal (e.g. INS o DEL within same GCI)
1241 _TE_ACTIVE
=14 // internal (node becomes active)
1245 * Specifies the durability of an event
1246 * (future version may supply other types)
1248 enum EventDurability
{
1250 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
1253 #if 0 // not supported
1255 // Only this API can use it
1256 // and it's deleted after api has disconnected or ndb has restarted
1259 // All API's can use it,
1260 // But's its removed when ndb is restarted
1262 ,ED_PERMANENT
///< All API's can use it.
1263 ///< It's still defined after a cluster system restart
1264 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
1270 * Specifies reporting options for table events
1274 ER_ALL
= 1, // except not-updated blob inlines
1280 * @param name Name of event
1282 Event(const char *name
);
1285 * @param name Name of event
1286 * @param table Reference retrieved from NdbDictionary
1288 Event(const char *name
, const NdbDictionary::Table
& table
);
1291 * Set unique identifier for the event
1293 int setName(const char *name
);
1295 * Get unique identifier for the event
1297 const char *getName() const;
1299 * Get table that the event is defined on
1301 * @return pointer to table or NULL if no table has been defined
1303 const NdbDictionary::Table
* getTable() const;
1305 * Define table on which events should be detected
1307 * @note calling this method will default to detection
1308 * of events on all columns. Calling subsequent
1309 * addEventColumn calls will override this.
1311 * @param table reference retrieved from NdbDictionary
1313 void setTable(const NdbDictionary::Table
& table
);
1315 * Set table for which events should be detected
1317 * @note preferred way is using setTable(const NdbDictionary::Table&)
1318 * or constructor with table object parameter
1320 int setTable(const char *tableName
);
1322 * Get table name for events
1324 * @return table name
1326 const char* getTableName() const;
1328 * Add type of event that should be detected
1330 void addTableEvent(const TableEvent te
);
1332 * Check if a specific table event will be detected
1334 bool getTableEvent(const TableEvent te
) const;
1336 * Set durability of the event
1338 void setDurability(EventDurability
);
1340 * Get durability of the event
1342 EventDurability
getDurability() const;
1344 * Set report option of the event
1346 void setReport(EventReport
);
1348 * Get report option of the event
1350 EventReport
getReport() const;
1351 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
1352 void addColumn(const Column
&c
);
1355 * Add a column on which events should be detected
1357 * @param attrId Column id
1359 * @note errors will mot be detected until createEvent() is called
1361 void addEventColumn(unsigned attrId
);
1363 * Add a column on which events should be detected
1365 * @param columnName Column name
1367 * @note errors will not be detected until createEvent() is called
1369 void addEventColumn(const char * columnName
);
1371 * Add several columns on which events should be detected
1373 * @param n Number of columns
1374 * @param columnNames Column names
1376 * @note errors will mot be detected until
1377 * NdbDictionary::Dictionary::createEvent() is called
1379 void addEventColumns(int n
, const char ** columnNames
);
1382 * Get no of columns defined in an Event
1384 * @return Number of columns, -1 on error
1386 int getNoOfEventColumns() const;
1389 * Get a specific column in the event
1391 const Column
* getEventColumn(unsigned no
) const;
1394 * The merge events flag is false by default. Setting it true
1395 * implies that events are merged in following ways:
1397 * - for given NdbEventOperation associated with this event,
1398 * events on same PK within same GCI are merged into single event
1400 * - a blob table event is created for each blob attribute
1401 * and blob events are handled as part of main table events
1403 * - blob post/pre data from the blob part events can be read
1404 * via NdbBlob methods as a single value
1406 * NOTE: Currently this flag is not inherited by NdbEventOperation
1407 * and must be set on NdbEventOperation explicitly.
1409 void mergeEvents(bool flag
);
1414 virtual Object::Status
getObjectStatus() const;
1417 * Get object version
1419 virtual int getObjectVersion() const;
1424 virtual int getObjectId() const;
1426 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
1431 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
1432 friend class NdbEventImpl
;
1433 friend class NdbEventOperationImpl
;
1435 class NdbEventImpl
& m_impl
;
1436 Event(NdbEventImpl
&);
1439 struct AutoGrowSpecification
{
1443 const char * filename_pattern
;
1447 * @class LogfileGroup
1449 class LogfileGroup
: public Object
{
1452 LogfileGroup(const LogfileGroup
&);
1453 virtual ~LogfileGroup();
1455 void setName(const char * name
);
1456 const char* getName() const;
1458 void setUndoBufferSize(Uint32 sz
);
1459 Uint32
getUndoBufferSize() const;
1461 void setAutoGrowSpecification(const AutoGrowSpecification
&);
1462 const AutoGrowSpecification
& getAutoGrowSpecification() const;
1464 Uint64
getUndoFreeWords() const;
1469 virtual Object::Status
getObjectStatus() const;
1472 * Get object version
1474 virtual int getObjectVersion() const;
1479 virtual int getObjectId() const;
1482 friend class NdbDictionaryImpl
;
1483 friend class NdbLogfileGroupImpl
;
1484 class NdbLogfileGroupImpl
& m_impl
;
1485 LogfileGroup(NdbLogfileGroupImpl
&);
1491 class Tablespace
: public Object
{
1494 Tablespace(const Tablespace
&);
1495 virtual ~Tablespace();
1497 void setName(const char * name
);
1498 const char* getName() const;
1500 void setExtentSize(Uint32 sz
);
1501 Uint32
getExtentSize() const;
1503 void setAutoGrowSpecification(const AutoGrowSpecification
&);
1504 const AutoGrowSpecification
& getAutoGrowSpecification() const;
1506 void setDefaultLogfileGroup(const char * name
);
1507 void setDefaultLogfileGroup(const class LogfileGroup
&);
1509 const char * getDefaultLogfileGroup() const;
1510 Uint32
getDefaultLogfileGroupId() const;
1515 virtual Object::Status
getObjectStatus() const;
1518 * Get object version
1520 virtual int getObjectVersion() const;
1525 virtual int getObjectId() const;
1528 friend class NdbTablespaceImpl
;
1529 class NdbTablespaceImpl
& m_impl
;
1530 Tablespace(NdbTablespaceImpl
&);
1533 class Datafile
: public Object
{
1536 Datafile(const Datafile
&);
1537 virtual ~Datafile();
1539 void setPath(const char * name
);
1540 const char* getPath() const;
1542 void setSize(Uint64
);
1543 Uint64
getSize() const;
1544 Uint64
getFree() const;
1546 int setTablespace(const char * name
);
1547 int setTablespace(const class Tablespace
&);
1548 const char * getTablespace() const;
1549 void getTablespaceId(ObjectId
* dst
) const;
1551 void setNode(Uint32 nodeId
);
1552 Uint32
getNode() const;
1554 Uint32
getFileNo() const;
1559 virtual Object::Status
getObjectStatus() const;
1562 * Get object version
1564 virtual int getObjectVersion() const;
1569 virtual int getObjectId() const;
1572 friend class NdbDatafileImpl
;
1573 class NdbDatafileImpl
& m_impl
;
1574 Datafile(NdbDatafileImpl
&);
1577 class Undofile
: public Object
{
1580 Undofile(const Undofile
&);
1581 virtual ~Undofile();
1583 void setPath(const char * path
);
1584 const char* getPath() const;
1586 void setSize(Uint64
);
1587 Uint64
getSize() const;
1589 void setLogfileGroup(const char * name
);
1590 void setLogfileGroup(const class LogfileGroup
&);
1591 const char * getLogfileGroup() const;
1592 void getLogfileGroupId(ObjectId
* dst
) const;
1594 void setNode(Uint32 nodeId
);
1595 Uint32
getNode() const;
1597 Uint32
getFileNo() const;
1602 virtual Object::Status
getObjectStatus() const;
1605 * Get object version
1607 virtual int getObjectVersion() const;
1612 virtual int getObjectId() const;
1615 friend class NdbUndofileImpl
;
1616 class NdbUndofileImpl
& m_impl
;
1617 Undofile(NdbUndofileImpl
&);
1622 * @brief Dictionary for defining and retreiving meta data
1628 * @brief Structure for retrieving lists of object names
1633 * @brief Object to be stored in an NdbDictionary::Dictionary::List
1636 unsigned id
; ///< Id of object
1637 Object::Type type
; ///< Type of object
1638 Object::State state
; ///< State of object
1639 Object::Store store
; ///< How object is logged
1640 Uint32 temp
; ///< Temporary status of object
1641 char * database
; ///< In what database the object resides
1642 char * schema
; ///< What schema the object is defined in
1643 char * name
; ///< Name of object
1646 type(Object::TypeUndefined
),
1647 state(Object::StateUndefined
),
1648 store(Object::StoreUndefined
),
1649 temp(NDB_TEMP_TAB_PERMANENT
),
1655 unsigned count
; ///< Number of elements in list
1656 Element
* elements
; ///< Pointer to array of elements
1657 List() : count(0), elements(0) {}
1659 if (elements
!= 0) {
1660 for (unsigned i
= 0; i
< count
; i
++) {
1661 delete[] elements
[i
].database
;
1662 delete[] elements
[i
].schema
;
1663 delete[] elements
[i
].name
;
1664 elements
[i
].name
= 0;
1679 * Fetch list of all objects, optionally restricted to given type.
1681 * @param list List of objects returned in the dictionary
1682 * @param type Restrict returned list to only contain objects of
1685 * @return -1 if error.
1688 int listObjects(List
& list
, Object::Type type
= Object::TypeUndefined
);
1689 int listObjects(List
& list
,
1690 Object::Type type
= Object::TypeUndefined
) const;
1693 * Get the latest error
1695 * @return Error object.
1697 const struct NdbError
& getNdbError() const;
1699 /** @} *******************************************************************/
1702 * @name Retrieving references to Tables and Indexes
1707 * Get table with given name, NULL if undefined
1708 * @param name Name of table to get
1709 * @return table if successful otherwise NULL.
1711 const Table
* getTable(const char * name
) const;
1713 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
1715 * Given main table, get blob table.
1717 const Table
* getBlobTable(const Table
*, const char * col_name
);
1718 const Table
* getBlobTable(const Table
*, Uint32 col_no
);
1721 * Save a table definition in dictionary cache
1722 * @param table Object to put into cache
1724 void putTable(const Table
* table
);
1728 * Get index with given name, NULL if undefined
1729 * @param indexName Name of index to get.
1730 * @param tableName Name of table that index belongs to.
1731 * @return index if successful, otherwise 0.
1733 const Index
* getIndex(const char * indexName
,
1734 const char * tableName
) const;
1737 * Fetch list of indexes of given table.
1738 * @param list Reference to list where to store the listed indexes
1739 * @param tableName Name of table that index belongs to.
1740 * @return 0 if successful, otherwise -1
1742 int listIndexes(List
& list
, const char * tableName
);
1743 int listIndexes(List
& list
, const char * tableName
) const;
1745 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
1747 * Fetch list of indexes of given table.
1748 * @param list Reference to list where to store the listed indexes
1749 * @param table Reference to table that index belongs to.
1750 * @return 0 if successful, otherwise -1
1752 int listIndexes(List
& list
, const Table
&table
) const;
1755 /** @} *******************************************************************/
1762 * Create event given defined Event instance
1763 * @param event Event to create
1764 * @return 0 if successful otherwise -1.
1766 int createEvent(const Event
&event
);
1769 * Drop event with given name
1770 * @param eventName Name of event to drop.
1771 * @return 0 if successful otherwise -1.
1773 int dropEvent(const char * eventName
);
1776 * Get event with given name.
1777 * @param eventName Name of event to get.
1778 * @return an Event if successful, otherwise NULL.
1780 const Event
* getEvent(const char * eventName
);
1782 /** @} *******************************************************************/
1785 * @name Table creation
1788 * These methods should normally not be used in an application as
1789 * the result will not be visible from the MySQL Server
1793 * Create defined table given defined Table instance
1794 * @param table Table to create
1795 * @return 0 if successful otherwise -1.
1797 int createTable(const Table
&table
);
1800 * Drop table given retrieved Table instance
1801 * @param table Table to drop
1802 * @return 0 if successful otherwise -1.
1804 int dropTable(Table
& table
);
1807 * Drop table given table name
1808 * @param name Name of table to drop
1809 * @return 0 if successful otherwise -1.
1811 int dropTable(const char * name
);
1813 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
1815 * Alter defined table given defined Table instance
1816 * @param table Table to alter
1817 * @return -2 (incompatible version) <br>
1818 * -1 general error <br>
1821 int alterTable(const Table
&table
);
1824 * Invalidate cached table object
1825 * @param name Name of table to invalidate
1827 void invalidateTable(const char * name
);
1831 * Remove table from local cache
1833 void removeCachedTable(const char * table
);
1835 * Remove index from local cache
1837 void removeCachedIndex(const char * index
, const char * table
);
1840 /** @} *******************************************************************/
1842 * @name Index creation
1845 * These methods should normally not be used in an application as
1846 * the result will not be visible from the MySQL Server
1851 * Create index given defined Index instance
1852 * @param index Index to create
1853 * @return 0 if successful otherwise -1.
1855 int createIndex(const Index
&index
);
1856 int createIndex(const Index
&index
, const Table
&table
);
1859 * Drop index with given name
1860 * @param indexName Name of index to drop.
1861 * @param tableName Name of table that index belongs to.
1862 * @return 0 if successful otherwise -1.
1864 int dropIndex(const char * indexName
,
1865 const char * tableName
);
1867 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
1868 void removeCachedTable(const Table
*table
);
1869 void removeCachedIndex(const Index
*index
);
1870 void invalidateTable(const Table
*table
);
1872 * Invalidate cached index object
1874 void invalidateIndex(const char * indexName
,
1875 const char * tableName
);
1876 void invalidateIndex(const Index
*index
);
1878 * Force gcp and wait for gcp complete
1883 /** @} *******************************************************************/
1885 /** @} *******************************************************************/
1887 * @name Disk data objects
1891 int createLogfileGroup(const LogfileGroup
&, ObjectId
* = 0);
1892 int dropLogfileGroup(const LogfileGroup
&);
1893 LogfileGroup
getLogfileGroup(const char * name
);
1895 int createTablespace(const Tablespace
&, ObjectId
* = 0);
1896 int dropTablespace(const Tablespace
&);
1897 Tablespace
getTablespace(const char * name
);
1898 Tablespace
getTablespace(Uint32 tablespaceId
);
1900 int createDatafile(const Datafile
&, bool overwrite_existing
= false, ObjectId
* = 0);
1901 int dropDatafile(const Datafile
&);
1902 Datafile
getDatafile(Uint32 node
, const char * path
);
1904 int createUndofile(const Undofile
&, bool overwrite_existing
= false, ObjectId
* = 0);
1905 int dropUndofile(const Undofile
&);
1906 Undofile
getUndofile(Uint32 node
, const char * path
);
1908 /** @} *******************************************************************/
1911 Dictionary(Ndb
& ndb
);
1915 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
1916 friend class NdbDictionaryImpl
;
1917 friend class UtilTransactions
;
1918 friend class NdbBlob
;
1920 class NdbDictionaryImpl
& m_impl
;
1921 Dictionary(NdbDictionaryImpl
&);
1922 const Table
* getIndexTable(const char * indexName
,
1923 const char * tableName
) const;
1925 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
1926 const Table
* getTable(const char * name
, void **data
) const;
1927 void set_local_table_data_size(unsigned sz
);
1929 const Index
* getIndexGlobal(const char * indexName
,
1930 const Table
&ndbtab
) const;
1931 const Table
* getTableGlobal(const char * tableName
) const;
1932 int alterTableGlobal(const Table
&f
, const Table
&t
);
1933 int dropTableGlobal(const Table
&ndbtab
);
1934 int dropIndexGlobal(const Index
&index
);
1935 int removeIndexGlobal(const Index
&ndbidx
, int invalidate
) const;
1936 int removeTableGlobal(const Table
&ndbtab
, int invalidate
) const;
1941 class NdbOut
& operator <<(class NdbOut
& out
, const NdbDictionary::Column
& col
);