Working with Database Libraries in Altium Designer

Altium Designer provides the ability to place components directly from a company database, by creating and using a Database Library. Placement is carried out from the Components panel which, after installing the database library, acts as a browser into your database.

After placement, design parameter information can be synchronized between placed components and their corresponding linked records in the database, using the Tools » Update Parameters From Database command. Full component updates - including the graphical symbol, model references, and parameters, can be performed using the Tools » Update From Libraries command. Parametric information from the database can also be included in the final Bill of Materials (BOM), ready for component procurement.

Direct Placement - Beyond Mere Linking

Altium Designer provides three methods of linking from a component to a database - using either a Database Link file (*.DbLink), a Database Library file (*.DbLib), or an SVN Database Library file (*.SVNDbLib) respectively. The DbLink approach provides an efficient means of linking and keeping the components used in your design (or libraries) synchronized with the data entered in the database. The DbLib/SVNDbLib approach takes this proven linking efficiency and adds to it the freedom to be able to place a component directly from the database - in essence creating the component dynamically from the information stored for it in the corresponding database record.

Before launching into the greater depths of the database library feature, it is worth discussing the differences between these methods, in regard to the way you use them.

Linking using a Database Link file

Related page: Linking Existing Components to Your Company Database

• Using this method, the Database Link file (*.DbLink) defines linkage between the schematic component and a matched record in a database. The record match is established by key field linking, which can be a single key field (for example a part number), or multiple key fields (by defining a Where clause).
• With this method of linking, the model and parameter information for the component must be predefined as part of the Altium Designer library component. The library component must also include the necessary key field information as part of it's definition. Once this has been defined you add a Database Link file to your Library Package, or Design project, then you can synchronize the component information (parameters) with the contents of fields in the database.
• Although each physical component defined by each database record does not need to map to a unique Altium Designer library component - many database components can share the same component symbol - this method of linking would typically be used in a "one database record-to-one Altium Designer component" fashion. The unique Altium Designer component can either be an instance placed on a schematic sheet, or a unique component in a component library.
• With DbLink-style database linking, you include the Database Link file with the library package, or design project.

Linking using a Database Library file

• Using this method, the Database Library file (*.DbLib) also defines the linkage between the schematic component and a matched record in a database. Again, the record match is established by key field linking, which can be a single key field (for example a part number), or multiple key fields (by defining a Where clause).
• The key difference with this method of linking is that the component symbol, model, and parameter information for a component is stored as part of the record definition for that component in the external database. The referenced schematic component (stored in an underlying component library (*.SchLib)) is only the symbol; it has no linked models, and no defined design parameters.
• When the component is placed, its parameter and model information is created on-the-fly, using the corresponding fields in the matched database record, and in accordance with defined mapping. One or more of these parameters will then be used to maintain an ongoing link back to the database, as per the matching criteria defined, enabling future synchronization after placement.
• This method of linking, due to its dynamic creation of components at the time of placement, lends itself very well to being used in a "many database records-to-one Altium Designer component" fashion.
• Unlike the DbLink-style of database linking, whereby the DbLink file must be included with the library package (or design project), the DbLib/SVNDbLib file need not be added to the project. The database library (DbLib) is included in the Available File-based Libraries - accessible by the Components panel. Remember, the Available File-based Libraries can consist of Project Libraries, Installed Libraries, or libraries found along specified search paths.
• You would typically configure DbLib/SVNDbLib files in a library-oriented fashion. For example you might have one for all the resistors detailed in your company database, another for capacitors, and so on.

DbLib vs SVNDbLib

An SVN Database Library is an extension of the Database Library model, with the difference being that the source symbol and models are stored under version control.

The source libraries are created, added-to, and maintained within, a Subversion-based repository. The link to the repository, and to the external database, is defined within an SVN Database Library file (*.SVNDbLib). And since this approach is an extension of the Database Library, it is often referred to as a Version-Controlled Database Library.

Librarian or Designer?

There are essentially two modes in which you can work with a version-controlled database library - as a Librarian, or as a Designer.

As a Librarian, not only will you need to set up and maintain the external source control repository of symbol and model libraries, but you will also be responsible for setting up the SVN Database Library file. This entails:

• Connecting to the external component database.
• Defining database record to component parameter/model mapping.
• Specifying the link to the SVN repository in which the symbol and model libraries are stored.

As a Designer, you will take the SVNDbLib file generated by the Librarian, and make it available in the Components panel - by adding it to the Available File-based Libraries list - so that you browse and place the database components.

The use of these roles will differ from company to company. A larger company may have a dedicated library center which will, in the role of Librarian, solely be involved with the setup and maintenance of the symbol and model libraries in the source control repository, and the generation of the SVN Database Library file(s). The SVNDbLib file(s) will then be made available to the Designer(s) within that company, who will install and use the library files from which to place the components in their designs.

In a smaller company, both roles may be filled by the same person. Not only will that person setup and maintain the repository of libraries, but will also use the defined SVNDbLib(s) in their design work.

The Source Control Repository

Related article: Using External Version Control

The symbol and model library files need to be added to a Subversion (SVN) repository. Altium Designer includes an SVN Version Control Provider, this is enabled and configured in the Data Management - Version Control page of the Preferences dialog. Once the SVN Version Control Provider has been enabled, a repository can be created on the Data Management - Design Repositories page of the Preferences dialog.

SVN repositories can also be created and managed outside of Altium Designer using an external SVN client and server, such as TortoiseSVN. An existing repository can be connected to in the Data Management - Design Repositories page of the Preferences dialog.

One important thing to note when adding files to the repository, is that each symbol and model must be stored in its own library file. In a regular library - which can hold any number of symbols/models - changing a single entry would result in all being marked by the version control system as having been modified. Having one symbol/model per library file plays to the nature of version control, allowing you to keep track of exactly what has been modified and what has not.

For the purposes of this document, it is assumed that the repository has already been created.

Using the Library Splitter Wizard

If the libraries for the symbols and models are being newly created, there is no problem ensuring only one symbol/model per file. Typically however, the source libraries will already exist. To simplify the job of separating these libraries into single-entity files for addition to the SVN repository, Altium Designer provides a splitting tool - the Library Splitter Wizard. The wizard enables you to quickly split multi-component schematic (*.SchLib) and PCB (*.PcbLib) libraries, into individual component libraries. The wizard is accessible from the Tools menu from the Schematic Library Editor, the PCB Library Editor, and the SVN Database Library Editor.

Split source libraries into one symbol/model per file, using the Library Splitter Wizard.

Setting up for the splitting process involves the following steps:

1. Adding the required source library files that you want to split (these need not reside in the same folder). Use the Libraries to Split page to choose the schematic or PCB library(ies) you want to split. Click the Add button to access a dialog to browse and add the desired library(ies) to the list. The added libraries will be split into individual component libraries later in the Wizard. The source libraries need not exist in the same folder. Use the Remove button to delete a selected library from the list.

   

2. Specifying the output directory. The Output Directories page is used to set the output directory(ies) for the individual component libraries. The listed Output Directory is the path where the split libraries will be placed. Click Change Output Directory to update the listed and selected directory, if needed. A dialog opens in which you can browse and select the updated folder for the output directory.

   By default, the output directory will be set to the same directory in which the source library is stored. Care should be taken if the original source libraries are all stored in the same source directory folder. If the output directories are not specified and are left at their defaults - pointing to the same source directory folder - you can end up with a very large mixture of single symbol and model libraries. Sifting through these when creating the repository structure may prove very time consuming.

   

   As the split library files will be added to the SVN repository, it can be a good idea to setup the folder structure that you want in the repository - in terms of the symbol/model files - locally on your hard disk. Once the structure is defined, copy the source libraries to their respective folders within that structure. You can then just leave the output directory settings for each source library at their defaults. After the split, the generated single library files will already be in the correct locations. You can then delete the original source library from each folder and add the folders to the repository, using the SVN client you have decided to use.

3. Configure additional options to control how the source libraries are split. These include, for a schematic component library, options that allow you to strip the parameter and/or model information from each constituent component - leaving just the bare symbol.

    
   Two iterations of the Split Libraries page; on the left: the Split Libraries page when converting a .PCBLib file. On the right: the Split Libraries page when converting a .SCHLib file.

   You can control how the libraries are split using the Options page. Use the drop-down (shown in the above image) to select how the new files are handled. Choose Overwrite Existing Files (default) will cause any newly-created files to overwrite any existing files. If Append Incrementing Number To File Names is chosen, the library splitter will scan through all the output directories selected on the previous page (Output Directories) and create a list of files to protect so that they are not overwritten. New component libraries with the same name will be appended with the suffix "_#Increment Number".

4. Once the source libraries and options have been specified the wizard will perform an analysis, the result of which is the set of single symbol/model libraries that will be created, listed for you to review. The name of each split library to be generated is shown, as well as the actual name of the schematic component/footprint model within that library. The original source library is also listed. The name used for a library will be the same as that used for the constituent compone nt/model.

   If any of the following characters have been used in the component/model name, they will be replaced by an underscore when creating the library name: '\', '/', '!', ''', '[', ']'.

   

   The component libraries that will be created can be reviewed on the Review page. The Splitted Library Name, Component Name and Source Library are listed to show the new files that will be created during the splitting process. A drop-down list of the data in each column can be easily accessed by clicking the down arrow on the right-hand side of each column. This feature is especially helpful when reviewing files of extremely large libraries.

5. Review the list of libraries to be created and then click Next to proceed with the splitting process and ultimately obtain the libraries to be added to the source control repository. After you have successfully completed the Wizard, click Finish to close.

   

Using the SVN Database Library Conversion Wizard

Another approach for converting existing libraries into an SVN-type database library is the SVN Database Library Conversion Wizard. This Wizard converts schematic, PCB, database and integrated libraries into SVN database libraries. The Wizard has a number of conversion-related options, including how the source libraries should be split, in which directories of which repository they should be stored, and the output directory for the created SVNDbLib and MDB database file. 

The wizard is accessible from the Tools menu when editing a PCB or Schematic library document.

The Wizard splits symbol and footprint libraries and checks them into a repository, and creates the SVNDbLib and the Access database files.

Where to Next?

Refer to the following pages to learn more about different aspects of working with database libraries:

• Creating & Defining the Database Library
• Modifying a Database Table
• Modifying Symbols & Footprints