Working with Database Libraries in Altium NEXUS

Parent page: Building & Maintaining Your Components and Libraries

Altium NEXUS 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 Update Parameters From Database command. Full component updates - including the graphical symbol, model references, and parameters, can be performed using the 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 NEXUS 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 NEXUS 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 NEXUS 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 NEXUS component" fashion. The unique Altium NEXUS 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 NEXUS 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 NEXUS 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 NEXUS 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

Dialog page: 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 NEXUS provides a splitting tool - the Library Splitter Wizard. The wizard is accessible from the Tools menu when editing a PCB or Schematic library document.

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.
2. Specifying 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.

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.
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. The name used for a library will be the same as that used for the constituent component/model.

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.

Using the SVN Database Library Conversion Wizard

Dialog page: 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.

Creating the Database Library File

The backbone of the database library feature is the database library file. This comes in two forms, depending on whether you are using a standard database library, or a version-controlled database library:

• Standard Database Library - the Database Library file. This file is created and managed using Altium NEXUS's DatabaseLib Editor. This editor becomes available when the active document in the main design window is a *.DbLib file.
• Version-Controlled Database Library - the SVN Database Library file. This file is created and managed using Altium NEXUS's SVNDatabaseLib Editor. This editor becomes available when the active document in the main design window is a *.SVNDbLib file.

Example DbLib file, open in the DatabaseLib Editor. Hover over the image to see an example SVNDbLib file, open in the SVNDatabaseLib Editor.

Create a new file of these types by choosing the File » New » Library command from the main menus and selecting the Database Library or SVN Database Library option from the Database region of the New Library dialog that opens.

Connecting to an External Database

Table and mapping data will only appear in an Editor's main display window after the active Database Library/SVN Database Library file is successfully connected to the required external database. Connection is defined using the controls provided in the Source of Connection region.

Specifying the connection to the external database through a DbLib file. Hover over the image to see connection through an SVNDbLib file.

Any database which provides OLE DB support can be connected to. The options provided in this region each use an OLE DB connection string to connect to the target database. Some databases may not offer OLE DB support. However, virtually all Database Management Systems in use today can be accessed through the Open Database Connectivity (ODBC) interface. The database link feature uses Microsoft's ODBC provider, which allows an ADO (ActiveX Data Object) to connect to any ODBC data source. The result is that any ODBC database can be connected to. The OLE DB provider for the ODBC database is specified as part of the connection string.

Fast Connection to Access and Excel Databases

The Select Database Type option offers an expedited method of creating a connection string when the target database has been created using Microsoft Access, or Microsoft Excel. Using this option, select the database type and then browse to and select the required database file. The corresponding connection string will automatically be composed and entered into the field for the Use Connection String option.

Building a Connection String

If your company database is not Access or Excel-based, and you want to build the connection string explicitly, enable the Use Connection String option and then click the associated Build button to the right. The Data Link Properties dialog will appear.

Building a connection string through the Data Link Properties dialog.

The dialog opens at the Connection tab. The OLE DB Provider Microsoft Office <Version> Access Database Engine OLE DB Provider is set by default on the Provider tab of the dialog. This is the default provider setting for new Database Library/SVN Database Library files and is also used to connect to Access database files (*.mdb). Change the provider as necessary.

From the Connection tab enter the name (including path) of the database you wish to connect to.

If your database requires login permission, enter this as required, along with any other advanced settings available from the Advanced tab of the dialog. The All tab provides a summary listing of link options defined, as well as extended options relating to the chosen OLE DB Provider. Options can be modified as required from this tab.

Once link options have been defined you can check for successful connection by clicking on the Test Connection button (on the Connection tab). A successful connection will yield a confirmation dialog to that effect.

Specifying a Data Link file

If the data source to which you wish to connect is described using a Microsoft Data Link file (*.udl), enable the third of the connection options - Use Data Link File - and click the associated Browse button to locate the required file. A Data Link File is essentially a storage vessel for a connection string.

Proceeding with Connection

After defining the connection to the external database, the text of the Connect button will become bold, signifying that you can proceed with the connection. If the connection details are correct, the table and mapping information for the target database will be loaded into the Database Library/SVN Database Library file. The text on the Connect button will change to Connected and the button will be grayed-out.

If there is a problem with the connection details, for example a connection string is built incorrectly, or a path is entered erroneously, connection will fail and a message will appear alerting you to this fact. Check your connection settings and click the Connect button again.

Examples of flagging connection failure in a database library.

After successful initial connection, and after saving the Database Library/SVN Database Library file, the connection will be made automatically each time the file is opened, provided the target database's location and filename are not changed.

Specifying the Link to the Version Control Repository (SVNDbLib Only)

With a DbLib, the symbol and model libraries are stored on your hard disk, or other local/network medium. Remember that for an SVNDbLib, these libraries are stored under version control in a Subversion repository. As part of the SVNDbLib file, you must define the link to this repository. The connection to the SVN repository is defined on the SVN Repository tab of the Database Library Options dialog (Tools » Options). This dialog can also be accessed by clicking the Options button in the Field Settings region of the document view.

Example connection to a file-based SVN repository.

Database Table Listing

After successful connection to the external database, table and mapping data will be loaded. The left-hand side of the DbLib/SVNDbLib document lists all tables that exist in the connected database.

Tables existing in the connected database.

The Enable option next to each table entry allows you to control whether or not that table is to be part of the resulting database library. When the database library is added to the list of Available File-based Libraries for browsing in the Components panel, each table will appear as a separate library entity. So although only one database library is added in real terms, from the perspective of the Components panel it is as though you have added multiple, distinct libraries. For more information, see Making the Database Library Available.

As you click on a table entry in the list, its icon changes from  to  in order to distinguish it as being the currently active table. The table - with all its data - appears on the Table Browser tab of the document. This is an editable view of the table, and allows you to quickly refer to its contents, and edit where required, without having to launch the external database itself.

Browsing a source table in the connected database.

Specifying Matching Criteria

After a component has been placed from the external database, there needs to be some way of retaining the link between that placed component and the database record whose information was used to create it. In essence, the two need to be matched.

When a component is placed, its parameter information is created on-the-fly, using the corresponding fields in the database record. The post-placement link between the schematic component and the database record is established using one or more of these parameters. The Field Settings region of the document allows you to define the matching criteria - either a simple, single key lookup, or a more advanced match using a Where clause.

Controlling post-placement matching criteria.

Single Key Lookup

If the Single key lookup option is enabled (default) the Database field and Part parameter fields become available. The former lists all of the available field names (column headers) in the active table of the database. As the parameters for a schematic component are added as it is placed, the Part parameter field will reflect whatever database field is chosen.

Typically, the lookup key field used is something that uniquely identifies each component in the external database, such as a Part Number. The chosen lookup field is distinguished on the Field Mappings tab of the document by the Design Parameter entry shown as grayed-out.

Single key mapping by Part Number.

When using the Update Parameters From Database feature at some stage after placement, information is read from the chosen key parameter in the placed schematic components and then searched for in the chosen (key) field of the database - across all enabled tables. When there is a match, information from other cells in that record of the parent table can then be taken back to the mapped parameters in the schematic component.

Advanced Matching - the Where Clause

While the Single key lookup option works well if there is a unique part number/id to match on, it is not so effective when matching by a parameter that is not unique, such as capacitance or resistance. In this case the more advanced Where clause should be used, enabling you to specify multiple key matching in order to link the schematic component to its source database record.

In its simplest form the Where clause (written using SQL syntax) reflects the chosen entries that define the single key lookup. For example if the Database field was chosen to be Part Number - the default - the Part parameter field would automatically be set to Part Number also, and the entry for the Where clause would be :

[Part Number] = '{Part Number}'

The square brackets around the database field (table column) are quote characters, as specified on the Advanced tab of the Database Connection dialog. Access this dialog either by clicking on the Advanced button in the Source of Connection region of the document, or from the main Tools menu.

The Advanced tab of the Database Connection dialog provides additional SQL options for quoting
tables, or using table schema names, in a constructed Where clause.

The curly brackets (braces) specify that the entry being referenced is a design parameter. The single quotes are used to specify the design parameter be treated as a string, as opposed to a number (no quotes). The type matching is very important, as SQL is type sensitive. The design parameter should be made the same type as the column in the database.

Using standard SQL syntax, the Where clause can then be extended to match using multiple Database field/Part parameter entries, for example:

[Capacitance] = '{Capacitance}' AND [Tolerance] = {Tolerance} AND [Manufacturer] = '{Manufacturer}'

In this case a single record in the relevant table of the database would be linked to, using three different design parameters. Notice that the entry for the Tolerance design parameter is not quoted. This means that the column type in the associated table of the database is Number and not String.

Using standard SQL syntax you can conceivably make the Where clause as simple or as complicated as you like.

Mapping Database Fields to Design Parameters

Design parameters for a component placed from a database library are created/added at the time of placement. Which parameters are actually created, and the options used to update their information after placement - using the Update Parameters From Database command - is determined by mapping and update information specified in the Database Library/SVN Database Library file. These settings are performed on the Field Mappings tab of the main document view.

Specify parameter mapping and update options on the Field Mappings tab of the DbLib/SVNDbLib document.

Model and Parameter Mapping

The first two columns (from the left) on the Field Mappings tab are used to control which information from the database is to be mapped to the component's attributes, models and parameters.

• Database Field Name - this column lists all field (column) names in the currently active table of the database.
• Design Parameter - this column defines how each corresponding field in the database is to be used. This could be to source a component's symbol or footprint model (it will be enclosed in square brackets), or if it is to be included as a component parameter (these are not enclosed in brackets).

Initial mapping is performed automatically upon connection to the database, with all database fields mapped.

Attributes & Models

If the database field name is one of the following reserved names, the corresponding attribute/model mapping entry will be automatically set in the Design Parameter field:

• Description → [Description]
• Footprint Ref → [Footprint Ref]
• Footprint Path → [Footprint Path]
• Footprint Ref n → [Footprint Ref n]
• Footprint Path n → [Footprint Path n]

• Library Ref → [Library Ref]
• Library Path → [Library Path]
• Orcad Footprint → [Orcad Footprint]
• Orcad Library → [Orcad Library]

• PCB3D Ref → [PCB3D Ref]
• PCB3D Path → [PCB3D Path]

• Sim Description → [Sim Description]
• Sim Excluded Parts → [Sim Excluded Parts]
• Sim File → [Sim File]
• Sim Kind → [Sim Kind]
• Sim Model Name → [Sim Model Name]
• Sim Netlist → [Sim Netlist]
• Sim Parameters → [Sim Parameters]
• Sim Port Map → [Sim Port Map]
• Sim Spice Prefix → [Sim Spice Prefix]
• Sim SubKind → [Sim SubKind]

These mappings define the component attribute and model information for the component. When the component is placed, the schematic symbol specified by the corresponding database record's [Library Ref] field will be extracted from the specified schematic library. Similarly, PCB footprint and Simulation model information stored in the record will be added to the component as linked footprint and simulation models respectively.

The [Library Ref] entry must exist in the Design Parameter column and be mapped to the Database Field Name that specifies the schematic symbol, to be able to place a component from the Database Library/SVN Database Library onto a schematic. If the database table contains the symbol reference under a different Database Field Name, for example SCH Symbol, you will need to manually set the associated Design Parameter entry for this field to [Library Ref], using the available drop-down list for that cell.

Similarly, if model reference information is entered into the database using different field naming, you will need to manually map by choosing the appropriate Design Parameter entry ([Footprint Ref], [Footprint Ref n], [PCB3D Ref], [Sim Model Name], and so on) from the drop-down list, for each field in turn.

In order to define the symbol and model information for a component upon placement, it is the symbol and model reference fields in the database that are the crucial
mapping entities - ensure that there is a symbol and at least one PCB footprint reference as part of the defined mapping.

Parameters

All other database field names will be automatically mapped to design parameters using the same names. For example, if a field in the database is called Tolerance, a design parameter with the name Tolerance will be mapped to it. You can change the name for a design parameter by clicking in its cell and typing the new name directly. It is these design parameter names that will appear in the Parameters region of the component's associated properties dialog, once it has been placed on a schematic sheet.

You may have a large number of data fields associated with a component in the database, not all of which you will want, or even need, added as design parameters to the component when placed on a schematic sheet. Much of this information may only be required when generating a Bill of Materials. The Report Manager dialog allows you to add parameter information to a BOM, directly from a linked database - allowing you to reduce the amount of information that gets 'carried' with the schematic source documents. For more information, refer to the section Adding Database Information Directly to a BOM.

For fields that you explicitly do not want mapped from the database, set the Design Parameter entry to [None]. Unmapped database fields are distinguished on the tab by the use of a red cross icon (). Mapped database fields are distinguished by a green tick icon ().

Configure parameter mapping as required. Set to [None] to prevent a parameter in the database being mapped to the placed component.
Un-mapped parameters can be included directly in the BOM, if required.

Parameter Update Options

The remaining columns on the Field Mappings tab allow you to specify the actions taken for parameters, when placing a component from the database library for the first time, or updating a component after it has been placed using the Update Parameters From Database command.

The four columns are as follows:

• Update Values - a cell in this column is used to determine the action that should be taken if the parameter exists both on a schematic sheet and in the database, but the values are currently different. Choose to update the parameter of the placed component with the value stored in the database (Update), or not to update at all (Do not update). This option is obeyed when using the Update Parameters From Database command, after the component is placed.
• Add To Design - a cell in this column is used to determine the action that should be taken if the parameter is found in the database, but does not exist for the placed component. You can choose to add the parameter (Add), not add the parameter (Do not add), or add the parameter only if it has a value assigned to it in the database (Add only if not blank in database). This option is obeyed both when initially placing the component from the database library and when using the Update Parameters From Database command, after the component has been placed.
• Visible On Add - a checkbox in this column is used to determine whether a newly added parameter, resulting from initial placement or update after placement, is made visible for the component on the schematic sheet (enabled) or not (disabled).
• Remove From Design - a cell in this column is used to determine the action that should be taken if the parameter is found to exist for the placed component, but either is not in the database, or is, but has no value. You can choose to not remove the parameter at all (Do not remove), or only remove it if it has no value assigned to it in the database (Remove only if blank in database). This option is obeyed when using the Update Parameters From Database command, after the component has been placed.

Initially, the Update Values, Add To Design, and Remove From Design fields - for each mapped database field - will be set to the entry Default, and the Visible On Add option will be disabled, as illustrated in the following image.

Initial (default) parameter update options.

Looking at the image, there are four important points to make regarding update options:

1. Unmapped database fields will have no associated update options.
2. Attribute and Model based mappings (entries with square brackets in the Design Parameter column) will have no associated update options, as these are not design parameters.
3. The key field (e.g. Part Number in the image) will have no associated update options. This field is solely used for parameter matching purposes.
4. A setting of Default causes an update option to follow its corresponding default definition, as specified on the Default Actions tab of the Database Library Options dialog (Tools » Options). This dialog can also be accessed by clicking the Options button in the Field Settings region of the document view.

Define default parameter update options in a central location for a DbLib. Hover over
the image to see the equivalent for an SVNDbLib.

The fourth point is beneficial in that it allows you to specify update options from a central location, and then point to that location when defining the update options for each mapped field. That is why the Default entry is loaded automatically into the relevant update fields upon mapping a database field to a design parameter.

Should you wish to override the default setting for an update option, click inside the relevant update field, on the Field Mappings tab, then click again to access a drop-down providing the applicable update choices.

Parameter update options can be manually overridden, if required.

In this way, you have full control over how the parameters in the design are updated. You can set all fields to Default and make the required update decisions from the Database Library Options dialog, set each update field individually, or have a mixture of the two - the decision is entirely yours to make as you see fit. For placed components the update, when performed, is carried out through use of an Engineering Change Order dialog. If at this stage there are updates that you would prefer not to make, you can opt to not include those particular changes - giving you the final, and ultimate say, in which design parameters get updated.

Specifying Symbol and Model Library Locations

When you place a component from a database library its symbol - specified by the [Library Ref] mapping - is extracted from the specified schematic library (*.SchLib). Similarly, any model references (footprint, PCB3D, simulation) specified in the database will reside in underlying PCB Library (*.PcbLib), PCB3D Library (*.PCB3DLib) and Simulation Model (*.mdl, *.ckt) files. The paths to these files can be specified explicitly in the database by:

• Entering an absolute path to the file.
• Entering a relative path to the file.

If you have defined fields in your database for path information, these fields need to be mapped to the appropriate design parameters - [Library Path], [Footprint Path], [PCB3D Path], [Sim File], and so on (refer back to Model and Parameter Mapping).

Entering paths - even relative - in a database table can be a little restrictive. If you move the location of a library or model file, you would need to update the database table accordingly. To give you greater freedom, you have the ability to specify library search information within the DbLib/SVNDbLib file itself. This allows you to specify the name of the source library or model file in the database, or not to define it at all.

For a Database Library

For a DbLib, library search paths are defined on the Symbol and Model Search Paths tab of the Database Library Options dialog (Tools » Options). This dialog can also be accessed by clicking the Options button in the Field Settings region of the document view.

Specifying search paths for symbol and model libraries.

To add a path to the list:

1. Either type the path directly into the field below the Library Search Paths region, or click on the  button to access the Browse for Folder dialog, from where you can locate the directory in which the required library/model file(s) reside.
2. You can add either as a full path, or as a relative path (relative to the location of the DbLib file). Control this using the Add/Update As Relative Path option.
3. After specifying the required path, add it to the search paths list by clicking the Add button.
4. Continue adding additional search paths as required.

The library search paths determine where library and model files can be found when placing form the database library and when searching for a model after placement. The specific model that is used will depend on how you have set up your library search paths and whether you have added specific library information into your database. The searching will proceed in the following order:

1. If a full path exists in the mapped path field for the symbol or model, use that library/model file and extract the symbol or model specified in the applicable reference field.
2. If a relative path exists in the mapped path field for the symbol or model, use that library/model file and extract the symbol or model specified in the applicable reference field.
3. If only a library/model file name exists in the mapped path field for the symbol or model, use the search paths to locate the first library/model file that matches the specified name and which contains a match for the symbol or model specified in the applicable reference field.
4. If no library/model file information exists in the database, use the search paths to locate the first library/model file containing a match for the symbol or model specified in the applicable reference field.

For an SVN Database Library

For an SVNDbLib, the base directories within the Subversion repository - in which the symbols and footprint models reside - are specified on the SVN Repository tab of the Database Library Options dialog (Tools » Options). This dialog can also be accessed by clicking the Options button in the Field Settings region of the document view.

Specifying base repository directories for symbols and footprints.

Use the available fields in the Models Location region to specify the base directory for the symbols and footprints. Click the  button at the right of a field to access the Browse for directory dialog - a window into the linked repository. Use this dialog to select the required folder.

Browsing for the relevant directory in the linked SVN repository.

The model locations determine where library and model files can be found when placing form the version-controlled database library and when searching for a model after placement. The specific schematic symbol and footprint model(s) used will depend on how you have set up these locations, and whether you have added specific library information into your database. The searching will proceed in the following order:

1. If a full path exists in the mapped path field for the symbol or footprint model (e.g. http://MyServer/svn/MyCompany/ParentDirectory/SchematicSymbols/Capacitor_NonPolarized.SchLib), use that library file and extract the symbol or footprint specified in the applicable reference field.
2. If a relative path (relative to the root of the repository) exists in the mapped path field for the symbol or footprint model (e.g. /ParentDirectory/SchematicSymbols/Capacitor_NonPolarized.SchLib), use that library file and extract the symbol or footprint specified in the applicable reference field. The URL for the repository - specified in the Repository Server Connection region of the dialog - will be prefixed to the path you enter, to give the absolute address.
3. If only a library file name exists in the mapped path field for the symbol or footprint model (e.g. Capacitor_NonPolarized.SchLib), use the specified model locations within the repository to locate the first library file that matches the specified name, and which contains a match for the symbol or footprint model specified in the applicable reference field.

4. If no library file information exists in the database, use the specified model locations to locate the first library file containing a match for the symbol or footprint model specified in the applicable reference field.

Modifying a Database Table

The occasion will often arise where a change is required to a component record in the database. An existing component may need one or more of its fields updated to better reflect its current status. A new component may be available for use and therefore needs to be added to the relevant database table. Supply chain information may need to be added to components. A component may have been marked as 'obsolete' and, no longer to be used in designs, is required to be deleted from the database altogether.

Both the DatabaseLib Editor and the SVNDatabaseLib Editor enable you to perform these actions directly, through the Table Browser, eliminating the need to open the external database. With the required table selected, commands for manipulating its entries in the database are available from the right-click menu.

Accessing commands to modify the selected table in the linked database.

Editing an Existing Component

An existing component record in a linked database table can be modified in two ways:

• In-place Editing - click within the required field and modify its value as required. Press Enter, or click away from the field when done, and click Yes in the subsequent dialog that asks you to confirm committal of the change (committing it to the database).
• Dialog-based Editing - right-click on the entry for the required component record, and choose the Edit Component command from the context menu. An editing dialog for that component will appear, listing all of the fields for the parent database table, along with their values. Click on a Field Value entry to edit it. Click OK when you have finished modifying the desired fields, to commit the changes back to the database.

Demonstrating component record field editing, using the two editing methods.

Adding a New Component

To add a new component to a database table, right-click anywhere within the Table Browser and choose the Add New Component command from the context menu. The New Component dialog will appear, with all of the fields for the parent database table listed. Enter the information for this new physical component as required, then click OK. The new component will be added to the bottom of the table.

Demonstrating the addition of a new component to a table in the linked database.

Removing an Existing Component

To permanently remove an existing component from a database table, right-click on its entry in the Table Browser and choose the Delete Component command from the context menu. A confirmation dialog will appear - click Yes to proceed with the removal.

Managing Supply Chain Information

Related page: Linking to Supplier Data

Using Altium NEXUS's Live Supplier Data feature, you have the ability to search supplier databases from within Altium NEXUS, and link your design components to matching Supplier Items. For any given Supplier Item found through a search, you can also import its parameters, data sheet links, pricing, and stock information, as parameters of a target component in a DbLib/SVNDbLib). In addition, you can also create whole new components in the targeted database table - directly from Supplier Items! The linked supplier data can be included at design release time, in a Bill of Materials - especially useful from a project costing and procurement perspective.

At the heart of this feature is the Supplier Link. This fundamental entity provides the live link between an Altium NEXUS component and an item in a Supplier's database of electronic components.

Creation of a Supplier Link involves the addition of two parameters to the target Altium NEXUS component involved:

• Supplier n
• Supplier Part Number n

n is an integer suffix, used to distinguish between Supplier Items, where multiple links are added to the same component.

Adding Supplier Links

Creating a Supplier Link is a straightforward process. In a manual fashion, this process is facilitated most easily by using the Manufacturer Part Search panel to search for the required part. Once found, click to select the chosen item in the results region of the panel, when it is selected it will display a SPN dropdown (Supplier Part Number), as shown in the image below. Click the dropdown to display the SPN tiles, each tile details real-time information about the price and availability of the selected part, from that supplier.

Any of the suppliers shown can be added as a Supplier Link to the Database library.

Using the Manufacturer Part Search panel, a Supplier Link can be created in one of the following ways:

• By clicking and holding on the Supplier tile in the Manufacturer Part Search panel, and dragging and dropping it onto the component record in the Table Browser of the database library (shown in the animation below).
• By right-clicking on the Supplier tile in the Manufacturer Part Search panel, and choosing the Add Supplier Link To command. With the DbLib/SVNDbLib file active, the Supplier Link will be added to the focused component record.
• By right-clicking on the Supplier tile in the Manufacturer Part Search panel, and choosing the Add Supplier Link And Parameters To command. This command is used to add parameters, data sheet links, pricing and stock information for the selected Supplier Item, along with a Supplier Link to that item, all in the one step. With the DbLib/SVNDbLib file active, the parameters and Supplier Link will be added to the focused component record.
• When creating a new library component, by right-clicking on the Supplier tile in the Manufacturer Part Search panel, and choosing the Import Into LibraryName As ComponentName / PartNumber command. This command is used to create a new component in the target library DbLib/SVNDbLib directly from the selected Supplier Item. The ComponentName/PartNumber for the new component will be named using the Supplier Item's Manufacturer Part Number parameter. A Supplier Link to the item will be added to the component record, along with all parameters for that item (parameters, data sheet links, pricing and stock information).

Demonstrating the addition of a Supplier Link to a component record in the linked database.

Viewing/Editing Supplier Links

The Supplier Links currently defined for a database component can be viewed and edited using the Supplier Links for dialog. To access this dialog, right-click inside the record for the component, on the Table Browser tab of the active DbLib/SVNDbLib file, and choose the Edit Supplier Links command from the context menu.

An example of editing the currently defined Supplier Links for a selected database component. Click Add to open the Add Supplier Links dialog, and search for an additional supplier.

The Supplier Links for dialog lists all of the currently defined supplier links for the component.

In the dialog you can:

• Select a supplier and click the delete button (  ) to remove that supplier.
• Click and drag a supplier to change its position in the order of suppliers.
• Click the Add button to add an additional supplier. The Add Supplier Links dialog will appear, from where you can search for, and add an additional Supplier Link. Searching for Supplier Items is performed in the same way as when using the Manufacturer Part Search panel.

Modifying Symbols and Footprints

Besides maintaining the content within the database itself, there is also a requirement to maintain the referenced symbols and models, as and when necessary. This involves making modifications to the schematic symbols and the footprint model(s). And for a standard database library (DbLib), the definitions in simulation model files.

Both types of database library - standard and version-controlled - provide the ability to access the referenced symbol and footprint model for editing, directly from within the main DbLib/SVNDbLib document view when open as the active document. The following sections take a look at how to do so, which is a little more involved, but also a little more powerful, when using an SVNDbLib.

When using a DbLib

To open a component's referenced symbol/footprint model library file for editing, right-click on the component's entry in the Table Browser, then select the appropriate command - either Open Symbol, or Open Footprint - from the context menu. The applicable library file will be opened and the symbol/footprint presented as the active entity in the workspace, ready for you to perform your edits.

Once changes have been made as required, save the library file.

Example of accessing a database component's referenced symbol, directly from within the DbLib.

When using an SVNDbLib

As mentioned, the ability to access and edit the symbols and models referenced by database components, and accessed through an SVNDbLib file, is a little more complex, but also more powerful. Modifications are made to local working copies of the libraries stored in the SVN repository.

Specifying a Local Workspace

To make modifications to component symbols and footprint models, you will need to check the files out from the repository into a local working directory. Specify the required directory to be used on the Data Management - SVN Libraries page of the Preferences dialog. A default working folder location is defined - \Users\<ProfileName>\Documents\My Designs\SVNDBlib Working Folder. Change this as required by either clicking the  button to browse to an existing folder, or by entering a path to the folder directly.

Specifying a local working directory.

To quickly check out all symbol and footprint model libraries from the repository into the nominated local working folder, run the Check Out All Working Folders command from the SVNDatabaseLib Editor's main Tools menu. The folders checked out will be those specified in the Models Location region, on the SVN Repository tab of the Database Library Options dialog.

An example of the symbols and footprints - stored within the SVN repository and specified as part of the Database Library Options - checked out to a local working folder.

Making Changes

Once the symbol and footprint model libraries have been checked out to your designated local working folder, you can then make modifications as and when required. This involves making modifications to the local copy of the schematic symbols and footprint models, then committing these changes back to the SVN repository.

As with a DbLib, the following methods of accessing a symbol/model for editing are available:

• Within the SVNDbLib document, right-click on the component's entry in the Table Browser, then select the appropriate command - either Open Symbol, or Open Footprint - from the context menu.

• If the SVNDbLib is added to the Available File-based Libraries list, you can access edit commands directly through the Components panel. Select the required component entry, then use the Edit Symbol command (on the right-click context menu for the Components region) or Edit Footprint command (on the right-click context menu for the Models region), respectively.
• Use the library editor's File » Open command to browse to and open, the required library (in your local working folder).
• Drag-and-drop the library file (in your local working folder) from Windows Explorer directly into Altium NEXUS.

In each case, once changes have been made as required, save the library file.

However, the main interface between the folders and files checked out to the local working folder, and the repository itself, is the Storage Manager panel. When the SVNDbLib file is the active document, the Storage Manager panel will populate with the symbol and model folders checked out to the local working folder. The exact folders listed will be those specified in the Model Locations region, on the SVN Repository tab of the Database Library Options dialog.

The Storage Manager panel reflects the local working folder - provided the SVNDbLib file is the active document within Altium NEXUS.

To open a library file for editing, right-click on its entry in the All Files region of the panel, and choose Open from the context menu that appears. Make changes as required and save the file as normal using the associated Editor's standard Save command.

Committing Changes to the Repository

Panel page: Storage Manager

Although there are different ways to open a library for editing, committal of any changes made - from within Altium NEXUS - can only be carried out through the Storage Manager panel.

One of the most important things to remember when using the Storage Manager panel, is to refresh the status of the link between the local working folders/files (displayed in the panel) and the corresponding folders/files in the source control repository. For an individually-selected library, this is achieved using the Refresh command, available from the right-click menu in the All Files region of the panel. To quickly refresh the status of an entire folder, use the Ctrl+F5 keyboard shortcut.

Status entries pertinent to working with the local libraries of symbols and models are:

Icon	Status	Description
	No modification	The local copy of the library is identical to that of the repository. You are free to open the file and make modifications.
	Out of date	The local copy of the file (in the working folder) is older than its counterpart in the repository, and is therefore out of date. You will need to get the latest version of the file from the repository - updating your own local working copy - before you can modify and commit your own changes. Use the Update command (on the right-click context menu) to retrieve the latest file from the repository.
	Modified	The local copy of the file has been modified in Altium NEXUS and saved to the working folder. To push your local changes into the repository, right-click on the file's entry and choose the Commit command from the context menu. Once checked in to the repository, the status will return to No modification.
	Conflict	The file has been committed by another Altium NEXUS user before you have committed your own edited and saved version of that file. Use the Update or Resolve command to determine which version of the file will become the latest revision in the repository.
	Locked	The file has been locked by yourself or by another user. A locked file cannot be updated to a new revision in the repository by another user (unless it is forced to be unlocked). This state can be associated with other icons, such as those for Modified  or No Modification , when these status conditions also apply.

Physical Comparison of Revisions

Physical comparison can be performed between any two revisions of the same symbol (model library). This allows you to clearly see, in a visual manner, the changes that have been made - between consecutive or non-consecutive revisions of the file.

Within the Storage Manager panel, comparison is performed from the VCS Revisions region at the bottom of the panel.

The Storage Manager panel presents two views for the history of a selected file, with separate regions for the VCS Revisions and Local History.

Comparison can be made between any two revisions. Using the Windows Ctrl+click selection technique, select the two revisions of the library you wish to compare in the VCS Revisions region of the panel, right-click, and choose Compare.

Once the Compare command is invoked, the two selected document revisions will be opened side-by-side in the workspace, the graphical comparison is made, and any differences detected between the two will be listed in the Differences panel.

Graphical comparison directly in the library editor workspace.

Making the Database Library Available

Like any other library, a standard (or version-controlled) database library is made available through the Components panel by adding it to the Available File-based Libraries list. From the Components panel, click the Menu button (  ) at the top right to open the menu, and select the File-Based Libraries Preferences command. The Available File-based Libraries dialog will open. The DbLib/SVNDbLib can be added as a project library, or as part of the installed libraries - making it available to all projects and not just the active one. Alternatively, you can specify a search path to the folder in which the DbLib/SVNDbLib file resides.

Making a database library available for use by adding it as an installed library.

The Components panel now becomes a 'browsing window' into the linked external database, and the table(s) of components it contains.

Browsing the Database Components

Once the DbLib/SVNDbLib has been added to the Available File-based Libraries list, the components in the database will become available for browsing in the Components panel. Although only a single DbLib/SVNDbLib file is added, each table in the linked database will present as if it were a distinct library.

The top drop-down list in the panel will populate with entries of the form:

• <LibraryName>.DbLib - <TableName> or <LibraryName>.SVNDbLib - <TableName> ----where your database has tables
• <LibraryName>.DbLib - <SheetName>$ or <LibraryName>.SVNDbLib - <SheetName>$ ----where your database is comprised of sheets in an Excel spreadsheet.

Example of a loaded DbLib with three tables, another with one table, and an SVNDbLib with one table.

Each component entry in the panel corresponds to a record in that particular table of the database. In fact when browsing loaded database libraries, the Components panel behaves like a direct database browser. Symbol and model information is populated from the underlying symbol and model libraries pointed to by the relevant fields of the database (and in conjunction with search paths/locations defined).

Browsing components in an external database linked through a database library.

By default, only the Part Number and Library Ref fields are displayed in the component listing region of the panel. To 'expose' other fields in the database table, right-click in the region and choose Select Columns from the context menu. This will give you access to the Select Columns dialog, from where you can enable the display of any of the additional fields in that table.

Searching for a Component

The external database that you have connected to may include a number of tables, each with a sizeable amount of component records. Being able to place directly from a database is one thing, locating the specific component that you want to place can be more challenging. The Components panel supports two approaches to searching.

In-Panel Searching

The Components panel includes a Search field, enter a string and press Enter to search the current library for that string, anywhere within the visible component parameters.

You can perform a search directly in the Components panel.

Performing Detailed Searches

For more detailed searching, the File-Based Libraries Search dialog is used.

Click the Menu button at the top of the panel to open the File-Based Libraries Search dialog, from where you can conduct a search of database components in a single table of an installed DbLib/SVNDbLib file. To enable searching of database components, set the Search in field to Database Components and select the required Table. Note that the available Fields, listed in the drop-down above, will change to reflect the column headings available in the chosen table. The remaining options in the dialog become grayed-out, as they are not relevant when searching database libraries.

Accessing the File-based Libraries Search dialog.

The detailed search facility essentially offers two 'levels' of searching - Field-based and SQL-based querying.

Field-Based Search

This is a 'coarse' search that will return all database components found in the specified table. Click the Search button, at the bottom-left of the File-based Libraries Search dialog, to begin the search. The dialog will close and the results of the search will be listed back in the Components panel. After performing a search, the libraries drop-down list will contain the entry File Search, indicating that this list is the search results.

Example results after conducting a field-based search.

SQL Query Search

To perform an SQL query search, click the >>Advanced link in the Libraries Search dialog. The dialog will change, to look like that illustrated in the following image. This level of searching offers a 'fine' search based on a specified query expression, where you can enter an SQL query directly into the query editor section of the dialog.

Hover over the image to see how the dialog changes when you click Advanced, giving you access to a more
powerful SQL-based query search. Click Advanced again to come back to the simple-style search.

Localized Caching (SVNDbLib Only)

When an SVNDbLib file is added to the Available Libraries list, the symbol and model libraries in the repository are cached in a temporary folder, local to the Designer's computer. When an action in the software calls for the use of a schematic symbol, or model, that symbol/model is retrieved from the local cache.

Automatic Cache Update

The libraries in the cache will be automatically updated with the latest from the source control repository, when performing any of the following actions within the software:

• Placing a component from an installed SVNDbLib file (from the Components panel).
• Performing a design transfer (i.e. updating the PCB).
• Using the Update From Libraries command in the Schematic Editor.
• Using the Update From PCB Libraries command in the PCB Editor.

Although the update is automatic, it can be controlled by the use of an option available on the Data Management - SVN Libraries page of the Preferences dialog, highlighted in the following image.

Setting a minimum update time threshold for the local cache.

This option essentially provides an 'update timer' for the local cache. If the specified time has elapsed since the last time the cache was updated, then the cache will be updated automatically when one of the listed actions is performed. If an action is performed within this time, the current content of the cache will be used, which may be out of date compared to the content in the repository.

Manually Forcing an Update of the Cache

There may be times when you wish to force an update of the local cache, to ensure you have the most up-to-date libraries that are currently stored in the source control repository. For example, when gearing up to transfer the design from the schematic to the PCB.

You can force an update of the cache, manually, using one of the following methods:

• Using one of the Refresh commands available from a right-click menu in the Components panel.
• Uninstalling and re-installing the SVNDbLib file to the Available Libraries list.

Placing a Component

Placement is performed as it is for any other library loaded and available in the Components panel. With the target schematic sheet open as the active document, select the component you want to place from the panel and either right-click and select the Place command, or drag-and-drop the component directly onto the sheet. The component is built on-the-fly, with the following actions taking place:

• The schematic symbol specified in the database record is retrieved from the relevant schematic component library.
• Any referenced footprint model(s) are linked in (and any referenced simulation models, if using a DbLib).
• The design parameters specified in the DbLib/SVNDbLib file are added (in accordance with the associated Add To Design update setting) to the component.

After placement, double-click on the component on the schematic to open the Properties panel, where you can edit the component properties. On the General tab of the panel you will see:

• The value for Design Item ID (Component Name / Part Number). This is the chosen key field defined in the Field Settings region of the DbLib/SVNDbLib file, and is typically the part number.
• The name of the parent DbLib/SVNDbLib file - and the specific database table in which the component resides.
• The linked footprint and symbol models.

The design parameters will be detailed on the Parameters tab of of the panel.

Information added to a component placed from a database, linked-to using a DbLib file. Hover over the image to see the example when placed from a database that is linked-to
using an SVNDbLib file.

You can change the placed component to another from the same table by clicking the ellipsis button in the Design Item ID field (  ). This will open the Replace dialog, initially listing all components in the same table. In fact, you can change to a component in a different table of the same DbLib/SVNDbLib file, browse to one in a different File-based library, or place from a connected Workspace. The region will update accordingly with the new information for the chosen component.

Ensuring Synchronicity

After placement, the chosen key field parameter is used to ensure that the placed component on the schematic, retains its link to the corresponding record for that component in the external database. This means that at any stage in the future, changes to parameter and model information in the database can be easily passed back to the placed component, synchronizing the two.

If you want to update parameter information, use the Update Parameters From Database command, available from the Schematic Editor's main Tools menu.

To perform a full update, including parameters, model and graphical attributes of schematic symbols, use the Update From Libraries command (also available from the Schematic Editor's main Tools menu).

In the PCB Editor, use the Tools » Update From PCB Libraries command to update placed footprints with the latest information stored in the source libraries.

Dual Synchronization - DbLib/SVNDbLib and DBLink

You may have an existing design project where the majority of the placed parts have been linked to an external database using a DbLink file. Design changes may result in additional circuitry, the components for which might be placed using the Database Library feature. The associated DbLib/SVNDbLib file could, quite conceivably, point to a different external database.

When using the Update Parameters From Database command, all linked parameters for placed components will be queried - across all linked databases, irrespective of the linking method used - and detected differences for those parameters displayed in the Select Parameter Changes dialog.

Adding Database Information Directly to a BOM

Related page: BOM Configuration in the Report Manager

Source information for a Bill of Materials (BOM) has, in the past, been taken from the parameter information of the placed components for the design. But that can lead to a lot of information attached to a schematic that is only ever used for the BOM. If your placed Altium NEXUS components are linked to an external database using a database library file, the BOM Generator is able to extract any other record information that has not been added to the components as design parameters.

When configuring the Bill of Materials report using the Report Manager dialog, click the Database Parameters button (  ) in the Columns tab of the dialog to include them as a Source for the BOM, as shown below. This option will only be available if one or more components in your design are linked to an external database.

In the Columns listing, the icon is used to distinguish a parameter that exists for one or more placed components in a linked external database. Click the visibility icon so it becomes an eye (  ), to include that column (parameter) in your BOM.

Include additional component information that exists only in an external database.